Jobs API reference
Reference documentation for the Jobs HTTP endpoint.
The Jobs API lets you monitor processes running inside Sanity's infrastructure, such as dataset copy jobs.
Authentication
All requests must be authenticated.
Base API server URL
Sanity API base URL
https://api.sanity.io/{apiVersion}Variables
- apiVersionstringdefault:
"v2021-06-07"API version
Endpoints
Path parameters
Responses
Returns the status of the job.
- idstring
- statestring
- authorsarray
An array of author IDs.
Show child attributes
items
- string
- created_atstring (date-time)
- updated_atstring (date-time)
The job couldn't be found, or the request was invalid.
- statusCodeinteger
- errorstring
- messagestring
application/json{
"statusCode": 400,
"error": "Bad Request",
"message": "Could not get job status"
}The request isn't authenticated.
- statusCodeinteger
- errorstring
- messagestring
application/json{
"statusCode": 401,
"error": "Unauthorized",
"message": "A valid session is required for this endpoint"
}The job service failed to return the job.
- statusCodeinteger
- errorstring
- messagestring
application/json{
"statusCode": 500,
"error": "Internal Server Error",
"message": "An internal server error occurred"
}Listen for job updates
/jobs/{jobId}/listenEach job has a /listen endpoint that lets you monitor its status programmatically. While you're listening, the endpoint sends event data at intervals with updates on the status of your job.
The stream sends the following events. The data of each event is a JSON object.
welcome: The first event on the stream. Contains alistener_id.job: Contains the job'sjob_id,state, andprogress(0 to 100). When the job reaches a terminal state (completed,failed,terminating, orterminated), the endpoint sends a finaljobevent withprogressset to100and closes the stream.channel_error: Sent when an error occurs, such as an unknown job ID, or when the stream has been open for 12 hours. Contains anerrormessage.disconnect: Sent afterchannel_error, before the stream closes. Contains areason.
After the stream opens, the endpoint reports errors as events, not as HTTP status codes. If the job is deleted while you're listening, the stream closes without sending an event.
Path parameters
Responses
Streams job status events.
- string (binary)
text/event-streamevent: welcome
data: {"listener_id":"ladaicdbdo"}
event: job
data: {"job_id":"jacsfsmnxp","state":"running","progress":60}
event: job
data: {"job_id":"jacsfsmnxp","state":"completed","progress":100}
The request isn't authenticated.
- statusCodeinteger
- errorstring
- messagestring
application/json{
"statusCode": 401,
"error": "Unauthorized",
"message": "A valid session is required for this endpoint"
}