Socket Organization Snapshots API
Retrieve historical organization-level snapshots — point-in-time aggregations of dependencies, alerts, and risk metrics across all monitored repos. Used to populate trend dashboards and compliance posture reports.
OpenAPI Specification
openapi: 3.0.0
info:
description: Socket org snapshots API endpoints.
title: Socket Org Snapshots API
version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
/orgs/{org_slug}/historical/snapshots:
get:
tags:
- org-snapshots
summary: List details of periodic historical data snapshots (Beta)
operationId: historicalSnapshotsList
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: date
in: query
required: false
description: The UTC date in YYYY-MM-DD format for which to fetch snapshots
schema:
type: string
default: CURRENT_DATE
- name: range
in: query
required: false
description: The number of days of data to fetch as an offset from input date (e.g. "-7d" or "7d") or use "latest" to query for latest snapshots for each repo
schema:
type: string
default: -7d
- name: per_page
in: query
required: false
description: Specify the maximum number of results to return per page (intermediate pages may have fewer than this limit and callers should always check "endCursor" in response body to know if there
are more pages)
schema:
type: integer
minimum: 1
maximum: 10000
default: 10000
- name: startAfterCursor
in: query
required: false
description: The pagination cursor that was returned as the "endCursor" property in previous request
schema:
type: string
default: ''
- name: filters.status
in: query
required: false
description: 'Comma-separated list of historical snapshot statuses that should be included (allowed: "in-progress", "success", "failure", "timeout", "skipped")'
schema:
type: string
default: ''
- name: filters.requestId
in: query
required: false
description: Comma-separated list of requestId values that were used to start the historical snapshot job
schema:
type: string
default: ''
security:
- bearerAuth:
- historical:snapshots-list
- basicAuth:
- historical:snapshots-list
description: 'This API endpoint is used to list the details of historical snapshots.
Snapshots of organization data are taken periodically, and each historical snapshot record contains high-level overview metrics about the data that was collected.
Other [Historical Data Endpoints](/reference/historical-data-endpoints) can be used to fetch the raw data associated with each snapshot.
Historical snapshots contain details and raw data for the following resources:
- Repositories
- Alerts
- Dependencies
- Artifacts
- Users
- Settings
Daily snapshot data is bucketed to the nearest day which is described in more detail at: [Historical Data Endpoints](/reference/historical-data-endpoints)
This endpoint consumes 10 units of your quota.
This endpoint requires the following org token scopes:
- historical:snapshots-list'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
meta:
type: object
additionalProperties: false
description: ''
properties:
organizationId:
type: string
description: ''
default: ''
queryStartTimestamp:
type: number
description: ''
default: 0
startDateInclusive:
type: string
description: ''
default: ''
endDateInclusive:
type: string
description: ''
default: ''
filters:
type: object
additionalProperties: false
properties:
status:
type: array
items:
type: string
description: ''
default: ''
description: ''
requestId:
type: array
items:
type: string
description: ''
default: ''
description: ''
description: ''
required:
- endDateInclusive
- filters
- organizationId
- queryStartTimestamp
- startDateInclusive
items:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
id:
type: string
description: ''
default: ''
requestId:
type: string
description: ''
default: ''
requestedBy:
type: string
description: ''
default: ''
requestedAt:
type: string
description: ''
default: ''
startedAt:
type: string
description: ''
default: ''
finishedAt:
type: string
description: ''
default: ''
nullable: true
durationMs:
type: integer
description: ''
default: 0
status:
type: string
description: ''
default: ''
numReposScanned:
type: integer
description: ''
default: 0
numSbomsScanned:
type: integer
description: ''
default: 0
numLowAlerts:
type: integer
description: ''
default: 0
numHighAlerts:
type: integer
description: ''
default: 0
numMediumAlerts:
type: integer
description: ''
default: 0
numCriticalAlerts:
type: integer
description: ''
default: 0
numIgnoredLowAlerts:
type: integer
description: ''
default: 0
numIgnoredHighAlerts:
type: integer
description: ''
default: 0
numIgnoredMediumAlerts:
type: integer
description: ''
default: 0
numIgnoredCriticalAlerts:
type: integer
description: ''
default: 0
required:
- durationMs
- finishedAt
- id
- numCriticalAlerts
- numHighAlerts
- numIgnoredCriticalAlerts
- numIgnoredHighAlerts
- numIgnoredLowAlerts
- numIgnoredMediumAlerts
- numLowAlerts
- numMediumAlerts
- numReposScanned
- numSbomsScanned
- requestId
- requestedAt
- requestedBy
- startedAt
- status
description: ''
endCursor:
type: string
description: ''
default: ''
nullable: true
required:
- endCursor
- items
- meta
description: The historical snapshots.
'400':
$ref: '#/components/responses/SocketBadRequest'
'401':
$ref: '#/components/responses/SocketUnauthorized'
'403':
$ref: '#/components/responses/SocketForbidden'
'404':
$ref: '#/components/responses/SocketNotFoundResponse'
'429':
$ref: '#/components/responses/SocketTooManyRequestsResponse'
x-readme: {}
post:
tags:
- org-snapshots
summary: Start historical data snapshot job (Beta)
operationId: historicalSnapshotsStart
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
security:
- bearerAuth:
- historical:snapshots-start
- basicAuth:
- historical:snapshots-start
description: 'This API endpoint is used to start a historical snapshot job.
While snapshots are typically taken multiple times a day for paid plans and once a day for free plans, this endpoint can be used to start an "on demand" snapshot job to ensure the latest data is
collected and stored for historical purposes.
An historical snapshot will contain details and raw data for the following resources:
- Repositories
- Alerts
- Dependencies
- Artifacts
- Users
- Settings
Historical snapshot data is bucketed to the nearest day which is described in more detail at: [Historical Data Endpoints](/reference/historical-data-endpoints)
This endpoint consumes 10 units of your quota.
This endpoint requires the following org token scopes:
- historical:snapshots-start'
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
requestId:
type: string
description: ''
default: ''
requestedBy:
type: string
description: ''
default: ''
requestedAt:
type: string
description: ''
default: ''
required:
- requestId
- requestedAt
- requestedBy
description: The details of the snapshot job request.
'400':
$ref: '#/components/responses/SocketBadRequest'
'401':
$ref: '#/components/responses/SocketUnauthorized'
'403':
$ref: '#/components/responses/SocketForbidden'
'404':
$ref: '#/components/responses/SocketNotFoundResponse'
'429':
$ref: '#/components/responses/SocketTooManyRequestsResponse'
x-readme: {}
components:
requestBodies: {}
responses:
SocketBadRequest:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Bad request
SocketUnauthorized:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Unauthorized
SocketForbidden:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Insufficient max_quota for API method
SocketNotFoundResponse:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Resource not found
SocketTooManyRequestsResponse:
description: Insufficient quota for API route
headers:
Retry-After:
description: 'Retry contacting the endpoint *at least* after seconds.
See https://tools.ietf.org/html/rfc7231#section-7.1.3'
schema:
format: int32
type: integer
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
SocketInternalServerError:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Internal server error
SocketConflict:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Resource already exists
SocketGone:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Gone
schemas: {}
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Organization Tokens can be passed as a Bearer token
basicAuth:
type: http
scheme: basic
description: Organization Tokens can be passed as the user field in basic auth