canonical: https://jentic.com/apis/sanity.io/sanity-jobs

# Sanity Jobs HTTP Endpoint

The Sanity Jobs API reports on long-running processes inside Sanity's infrastructure, such as dataset copy jobs. A status call returns a job's id, its state (pending, running, completed, failed, terminating, or terminated), the author IDs behind it, and its created and updated timestamps. A listen stream sends a welcome event, then job events carrying the state and a progress value from 0 to 100, and closes with a final event once the job reaches a terminal state. Errors after the stream opens, such as an unknown job ID or a stream open for 12 hours, arrive as channel_error and disconnect events rather than HTTP status codes.

## For AI agents

Check the state of a Sanity background job such as a dataset copy, or stream its progress from 0 to 100 until it completes or fails.

## Scope

Does not start, cancel, or retry jobs, and does not copy datasets itself. Use for reading the status and progress of Sanity background jobs only.

## Capabilities

- Check a Sanity job's state, such as pending, running, completed, or failed, by its job ID
- See which author IDs started a job and when it was created and last updated
- Stream live job events with a progress value from 0 to 100 until the job reaches a terminal state
- Detect stream problems through channel_error and disconnect events, including an unknown job ID

## Use cases

### AI agent waiting on a dataset copy

An agent that clones a production dataset into staging before testing needs to know when the copy is done. Through Jentic it searches for 'check a Sanity job status', loads the job status operation, and polls it with the job ID returned by the copy request while the Sanity token is injected at call time. When the state reads completed it moves on; failed or terminated means it stops and reports.

Example prompt: Call GET `/jobs/{jobId}` for job jacsfsmnxp every 30 seconds until state is completed, failed, or terminated, then report the final state and updated_at

### Live progress display for long jobs

A deploy script or dashboard can show a job's progress instead of polling. The listen endpoint keeps a server-sent events stream open, sending job events with the current state and a progress percentage, and closes after a final event with progress 100 once the job ends. Streams are capped at 12 hours, after which a channel_error and disconnect event are sent.

Example prompt: Open GET `/jobs/{jobId}/listen` for job jacsfsmnxp and log each job event's state and progress until the stream closes

### Failed job triage

When a scheduled dataset copy does not land, the first question is what happened and who ran it. The job status response carries the final state, the author IDs that started the job, and its created_at and updated_at timestamps, so an agent can report a failed or terminated job with when it stopped and who to contact.

Example prompt: Call GET `/jobs/{jobId}` for job jacsfsmnxp and, if state is failed or terminated, report the authors, created_at, and updated_at values

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/jobs/{jobId}` | Get a job's status |
| GET | `/jobs/{jobId}/listen` | Stream job status and progress events |

## Key resources

- **Jobs** — Background processes such as dataset copies, with state, authors, and timestamps
- **Job events** — Server-sent welcome, job, channel_error, and disconnect events

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-jobs/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Jobs API by hand means templating the apiVersion into the host, sending a bearer token, and handling a server-sent events stream whose errors arrive as events rather than HTTP status codes. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Sanity puts the job ID in the URL path (`/jobs/{jobId}`), so a rule can pin your agent to one job. Both operations are reads, so the agent can follow a job but cannot start, change, or cancel anything through this API.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a Sanity job status' or 'wait for a dataset copy to finish', and Jentic returns the jobStatus or jobListen operation with its path parameter.

## Related APIs

- **Sanity Copy API** — Start the dataset copy jobs this API reports on
- **Sanity Backups API** — List and download dataset backups
- **Sanity HTTP API** — Query and mutate the content in the copied dataset

## FAQ

### What authentication does the Sanity Jobs API use?

Per its OpenAPI spec, the Sanity Jobs API uses a bearer token in the Authorization header, and both the status and listen calls return 401 without a valid one. Through Jentic the Sanity token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### What job states can the Sanity Jobs API return?

The status response lists the state as pending, running, completed, failed, terminating, or terminated. The listen stream treats completed, failed, terminating, and terminated as terminal: it sends a final job event with progress 100 and closes.

### How long can a Sanity job listen stream stay open?

The spec says a channel_error event is sent when the stream has been open for 12 hours, followed by a disconnect event before it closes. If the job is deleted while you are listening, the stream closes without sending an event, so fall back to the status call.

### What are the rate limits for the Sanity Jobs API?

The OpenAPI spec does not specify rate limits. Check the Sanity documentation at https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity MCP server?

You don't need an MCP server to give your agent the Sanity Jobs API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the job status or listen operation when it needs to wait on a job.

### How do I check a Sanity job's status through Jentic?

Search Jentic for 'check a Sanity job status', load the job status operation, and execute GET `/jobs/{jobId}` with the ID returned when the job was started. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Jobs API?

Yes. Write a rule that allows only GET `/jobs/jacsfsmnxp` and its listen stream, and the agent can follow that one copy job without seeing any other job on the account. Every call it makes is logged.
