> ## Documentation Index > Fetch the complete documentation index at: https://docs.retriever.run/llms.txt > Use this file to discover all available pages before exploring further. # Batch status and results > With `wait_seconds`, the request is held until no line is queued or running, or until the wait ends, whichever comes first: call it again the same way until `status` is `completed`. A restart on our side answers a held read at once. Without it the read answers at once. `status` is `completed` once every job has ended, whatever each one's outcome: read each job's `status`, `result` or `error`. `input_index` is the position in the list sent. ## OpenAPI ````yaml /openapi.yaml get /v1/services/jobs/batch/{id} openapi: 3.1.0 info: title: Retriever Public API version: 1.0.0 description: > Retriever public API: start the prospecting agent (runs), read and export tables, import data, sync exclusion lists, run structured research (Go), and call atomic services. **Model Context Protocol (MCP)**: the same account and credits are available through the hosted MCP server (`POST /mcp`, Streamable HTTP). See the MCP guide in this documentation (Model Context Protocol navigation). Primary tools: `service_discover`, `service_execute`, `service_batch_execute` and `service_batch_get` (the slow services), `retriever_build_list_start`, `table_*`, `sequence_*`, `inbox_*`. **Authentication**: `Authorization: Bearer ret_live_…`. Create the key in the app: Settings → **API keys** → **Create API key**. The key grants access to resources in the key owner's organization. **Errors**: every HTTP error has the shape `{ "error": { "code": "…", "message": "…", "details": … } }`. Branch your code on `error.code` (stable), never on `message`. **Rate limits**: key-authenticated responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (seconds). A `429` response also includes `Retry-After` (seconds). API error messages are in English. contact: name: Retriever servers: - url: https://api.retriever.run description: Production - url: http://localhost:4320 description: Local app-server security: - bearerAuth: [] tags: - name: Runs description: Prospecting agent « prompt in, table out ». Asynchronous. - name: Tables description: Read live tables in a workspace. - name: Workspaces description: Create workspaces and import tables. - name: Exclusions description: Company and people lists to never source. - name: Go description: Autonomous web research and structured extraction. - name: Services description: Atomic services (search, scraping, email…). - name: Credits description: Credit balance. paths: /v1/services/jobs/batch/{id}: get: tags: - Services summary: Batch status and results description: | With `wait_seconds`, the request is held until no line is queued or running, or until the wait ends, whichever comes first: call it again the same way until `status` is `completed`. A restart on our side answers a held read at once. Without it the read answers at once. `status` is `completed` once every job has ended, whatever each one's outcome: read each job's `status`, `result` or `error`. `input_index` is the position in the list sent. operationId: getServiceJobBatch parameters: - name: id in: path required: true schema: type: string - name: wait_seconds in: query required: false schema: type: integer minimum: 0 maximum: 60 default: 0 description: Seconds to wait for every line to end before answering. responses: '200': description: Batch. content: application/json: schema: $ref: '#/components/schemas/ServiceJobBatch' '400': description: '`invalid_request`: `wait_seconds` is not an integer from 0 to 60.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '404': description: '`not_found`: unknown batch.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: ServiceJobBatch: type: object properties: ok: type: boolean batch_id: type: string example: svcbatch_9f2c4b1e8a7d6c5f service: type: string size: type: integer status: type: string enum: - queued - running - completed description: '`completed` once every job has ended, whatever each one''s outcome.' counts: type: object properties: queued: type: integer running: type: integer completed: type: integer failed: type: integer cancelled: type: integer jobs: type: array description: One entry per input, in the order sent. items: allOf: - $ref: '#/components/schemas/ServiceJobLine' - type: object properties: input_index: type: integer poll_url: type: string Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable code; use in your application. message: type: string description: Human-readable explanation. May change. details: description: Optional details (e.g. list of invalid fields). ServiceJobLine: type: object properties: job_id: type: string service: type: string status: type: string enum: - queued - running - completed - failed - cancelled attempt: type: integer description: >- Number of times the provider call started (the current claim included). Becomes 2 if a restart resumed a started job. A restart before the call started does not count. reused: type: boolean description: >- `true` when the answer came from one your organization already paid for (a recent answer, or a job another list started): nothing was charged for it. On a batch line, also `true` for a line that points to a job another line or list created. result: type: object description: Present only if `completed`. error: type: object description: >- Present only if `failed`. Never a negative answer, and nothing was charged (except the Deep agent's miss price when a contact lookup's Deep agent finished its search). properties: code: type: string description: >- Retryable: `timeout`, `capacity`, `interrupted`, `provider_error`, `provider_unavailable`, `capability_error`, `service_error`, `service_execution_failed`, `worker_lost`, `usage_limit` (after a top-up). Not retryable: `provider_rejected`, `validation_error`, `invalid_output` (the service answered outside its own contract) and any other code. message: type: string retryable: type: boolean description: >- `true`: the same input can get an answer later (after a top-up for `usage_limit`), send it again in a new batch. `false`: it gets the same refusal. created_at: type: string format: date-time started_at: type: string format: date-time nullable: true description: When the provider call first started. Null while the job waits. completed_at: type: string format: date-time nullable: true responses: Unauthorized: description: >- `not_authenticated`: missing header, malformed (expected `Bearer `), revoked or unknown key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_authenticated message: A valid API key is required. TooManyRequests: description: '`rate_limited`: wait `Retry-After` seconds, then retry.' headers: Retry-After: schema: type: integer RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Rate limit exceeded. Retry later. headers: RateLimit-Limit: schema: type: integer description: Window budget. RateLimit-Remaining: schema: type: integer description: Remaining requests. RateLimit-Reset: schema: type: integer description: Seconds until reset. securitySchemes: bearerAuth: type: http scheme: bearer description: API key `ret_live_…` created in Settings → API keys. ````