> ## Documentation Index > Fetch the complete documentation index at: https://docs.valendata.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a background job > One job: its status, and once it ended, what came back. Poll this after [Start background jobs](/api-reference/jobs/start), about every 30 seconds, until `status` is `completed`, `failed`, or `cancelled`. Then `summary` is one plain line of what came back, `result` has the row `count` and a `preview` of the first rows, and `error` says why it failed. `cancel_requested` is `true` while a job is being stopped. `run_ref` is the run the job drives: read every row with [Get a run](/api-reference/runs/get). `link` is the page in Valendata that shows it. A `batch` job has no run of its own; the jobs in it have its id as their `group_id`. Only your own; anyone else gets `404`. Needs `jobs:read`. MCP tool: `get_job`. ## OpenAPI ````yaml GET /v1/jobs/{job_id} openapi: 3.1.0 info: title: Valendata REST API version: 1.0.0 description: >- Create, run, schedule, and improve skills and workflows over JSON and HTTPS. Every route is under `/v1`; changes inside v1 are additive only (new routes, new optional parameters, new response fields). A route that will go away is marked `deprecated` here and answers with `Deprecation`, `Sunset` and a `Link` to its replacement for at least six months before it is removed. Errors, limits, pagination and idempotency: https://docs.valendata.com/api-reference/errors. license: name: Proprietary url: https://www.valendata.com/terms-and-conditions servers: - url: https://api.valendata.com description: Production security: - ApiKeyAuth: [] - ApiKeyHeader: [] tags: - name: Skills description: List, create, read, update, and delete skills. - name: Marketplace description: Find a skill by the task, with its price per run and track record. - name: Runs description: Run skills and workflows, read any run, and cancel one. - name: Skill versions description: List, compare, restore, and pin a skill's versions. - name: Improvements description: >- Fix a skill, add fields, or re-learn its detail steps, and read its change history. - name: Schedules description: Run a skill or workflow on a fixed cadence. - name: Workflows description: List, create, read, update, and delete workflows. - name: Logins description: Saved website logins a skill can sign in with. - name: Connected apps description: >- Your own accounts (Gmail, Calendar, Slack …): connect them, list their tools, and run one. - name: Follow-ups description: >- Wait for something to arrive (a code, a link, a file, a message) or check back later, and read what came. - name: Jobs description: >- What your agents started to run in the background (skill runs, workflow runs, research), what came back, and stopping it. - name: Notes description: >- The notes on your Notes page: list and search them, read one, write, change, and delete them. - name: Account and usage description: Your plan, credit balance, and usage. - name: Webhooks description: The secret that signs webhook deliveries. paths: /v1/jobs/{job_id}: get: tags: - Jobs summary: Get a background job description: >- One job: `status` (`queued`, `running`, `completed`, `failed`, `cancelled`), and once it ended, `summary` (one plain line), `result` (`count` and a `preview` of the first rows) and `error`. `run_ref` is the run it drives: `GET /v1/runs/{run_id}` has every row. Only your own; anyone else gets 404. Needs `jobs:read`. operationId: get_job parameters: - name: job_id in: path required: true schema: type: string title: Job Id example: job_3f9a1c2b7d4e responses: '200': description: 'The job: once it ended, its summary and result.' content: application/json: schema: $ref: '#/components/schemas/Job' example: id: job_3f9a1c2b7d4e origin_kind: session origin_id: sess_8c1d2e3f group_id: null kind: skill label: eBay search target_id: skl_ebay_listings run_ref: run_5b6c7d8e9f0a status: completed summary: 12 results result: count: 12 preview: - title: Nikon F3 body price: $289 - title: Nikon F3HP, boxed price: $340 error: null cancel_requested: false attempts: 1 created_at: '2026-10-10T09:00:00Z' started_at: '2026-10-10T09:00:01Z' ended_at: '2026-10-10T09:02:40Z' link: /skills/runs/run_5b6c7d8e9f0a headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] - ApiKeyHeader: [] components: schemas: Job: properties: id: type: string title: Id origin_kind: type: string enum: - session - igris - brain - api title: Origin Kind description: >- Who started it: `session` (a chat session's agent), `igris` (the assistant), `brain` (a workflow's Brain, which may report results) or `api`. origin_id: type: string title: Origin Id description: >- The session or workflow that started it; empty for the assistant and the API. default: '' group_id: anyOf: - type: string - type: 'null' title: Group Id description: The batch job it belongs to, when several were started together. kind: type: string enum: - skill - workflow - research - batch title: Kind description: >- What it runs: a `skill`, a `workflow`, a `research` helper, or a `batch` grouping jobs started together. label: type: string title: Label description: What it is, in the words it was started with, e.g. 'eBay search'. default: '' target_id: type: string title: Target Id description: The skill or workflow it runs. default: '' run_ref: anyOf: - type: string - type: 'null' title: Run Ref description: >- The run it drives (GET /v1/runs/{run_id} for a skill or workflow); null until it has started. status: type: string enum: - queued - running - completed - failed - cancelled title: Status description: '`queued`, `running`, then one of `completed`, `failed`, `cancelled`.' summary: anyOf: - type: string - type: 'null' title: Summary description: One plain line of what came back, once it ended. result: anyOf: - additionalProperties: true type: object - type: 'null' title: Result description: >- A small result: `count` and a `preview` of the first rows. The run has the rest. error: anyOf: - type: string - type: 'null' title: Error description: Why it failed. cancel_requested: type: boolean title: Cancel Requested description: A stop was asked for; it ends `cancelled` soon. default: false attempts: type: integer title: Attempts description: How many times its run was started. default: 0 created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At ended_at: anyOf: - type: string format: date-time - type: 'null' title: Ended At link: type: string title: Link description: >- The path of the page in the Valendata app that shows its run (e.g. /skills/runs/run_…); empty until it has started. default: '' type: object required: - id - origin_kind - kind - status title: Job Error: type: object required: - detail - code - type - request_id properties: detail: description: What went wrong. A string, or an object for errors with more to say. oneOf: - type: string - additionalProperties: true type: object code: type: string description: >- Stable machine-readable code. Known values: `bad_request`, `invalid_json`, `invalid_cursor`, `invalid_idempotency_key`, `unauthorized`, `payment_required`, `permission_denied`, `not_found`, `method_not_allowed`, `conflict`, `app_not_connected`, `idempotency_key_in_use`, `idempotent_replay_unavailable`, `payload_too_large`, `unsupported_media_type`, `validation_error`, `idempotency_key_reused`, `rate_limited`, `internal_error`, `upstream_error`, `service_unavailable`. example: not_found type: type: string enum: - invalid_request_error - authentication_error - billing_error - permission_error - conflict_error - idempotency_error - rate_limit_error - api_error description: The broad category of the error. request_id: type: string description: Also in the `X-Request-ID` header. example: 3f9a1c2b7d4e param: type: string description: >- The field at fault, on validation errors (dotted path, e.g. `inputs.city`). errors: type: array items: additionalProperties: true type: object description: Every validation problem, on a 422 from request validation. headers: X-Request-ID: description: >- This request's id (yours, if you sent a valid `X-Request-ID`). Quote it to support. schema: type: string X-RateLimit-Limit: description: Requests a minute this API key may make. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current minute. schema: type: integer X-RateLimit-Reset: description: Unix time (seconds) the current window ends. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer responses: Unauthorized: description: The API key is missing, malformed, revoked, or expired. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: The API key is missing, malformed, revoked, or expired. code: unauthorized type: authentication_error request_id: 3f9a1c2b7d4e Forbidden: description: >- The key lacks a scope, is limited to other skills or workflows, or you may not do this. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: >- The key lacks a scope, is limited to other skills or workflows, or you may not do this. code: permission_denied type: permission_error request_id: 3f9a1c2b7d4e NotFound: description: It does not exist, or it is not yours to see. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: It does not exist, or it is not yours to see. code: not_found type: invalid_request_error request_id: 3f9a1c2b7d4e Unprocessable: description: >- A field is invalid (`param` names it), or the Idempotency-Key was used with a different request. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: 'Invalid request — name: Field required' code: validation_error type: invalid_request_error request_id: 3f9a1c2b7d4e param: name errors: - type: missing loc: - body - name msg: Field required RateLimited: description: >- Too many requests for this key, or too many runs in progress. Wait `Retry-After` seconds. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: >- Too many requests for this key, or too many runs in progress. Wait `Retry-After` seconds. code: rate_limited type: rate_limit_error request_id: 3f9a1c2b7d4e InternalError: description: >- Something broke on our side. Retry; runs that fail on our side are refunded. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: >- Something broke on our side. Retry; runs that fail on our side are refunded. code: internal_error type: api_error request_id: 3f9a1c2b7d4e securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: vd_sk_... description: >- API key with the `vd_sk_` prefix, as `Authorization: Bearer vd_sk_...`. Create keys in Settings → API Keys. ApiKeyHeader: type: apiKey in: header name: x-api-key description: The same API key in the `x-api-key` header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.