> ## Documentation Index > Fetch the complete documentation index at: https://exa.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > The Exa API is served at https://api.exa.ai. Authenticate with `Authorization: Bearer $EXA_API_KEY` (or `x-api-key: $EXA_API_KEY`); create keys at https://dashboard.exa.ai/api-keys?utm_source=docs&utm_medium=docs&utm_campaign=markdown_instructions. Every way an agent can get access to Exa is described at https://exa.ai/auth.md. > Prefer the official SDKs, `exa-py` (`pip install exa-py`) and `exa-js` (`npm install exa-js`); both read `EXA_API_KEY` from the environment. > Tool-using agents can call Exa without writing code through the hosted MCP server at https://mcp.exa.ai/mcp, or install the Exa agent skill with `npx skills add exa-labs/agent-skills` (skill file: https://exa.ai/docs/skill.md). > The OpenAPI specs at https://exa.ai/docs/exa-spec.yaml and https://exa.ai/docs/team-management-spec.yaml are the source of truth for request and response schemas. # Create a batch > Submit a batch of Exa API requests to run asynchronously. Each item in `requests` is a `POST` to `/search` or `/agent/runs` with a batch-unique `customId`. The same `customId` is returned in the results file so you can map output rows back to your input data. See the [Batch API guide](https://exa.ai/docs/batch/quickstart.md) for the end-to-end workflow. > [card] [Get your Exa API key](https://dashboard.exa.ai/api-keys?utm_source=docs\&utm_medium=docs\&utm_campaign=get_key_card) > > Create a key in the dashboard. New accounts start with free credits. ## OpenAPI ````yaml exa-spec.yaml POST /batches openapi: 3.1.0 info: title: Exa Public API version: 2.0.0 servers: - url: https://api.exa.ai security: - apiKey: [] - bearer: [] paths: /batches: post: tags: - Batches summary: Create a batch description: >- Create a batch of requests to run asynchronously. Each request is dispatched to its target route and results are made available for download when the batch completes. operationId: createBatch parameters: - $ref: '#/components/parameters/BatchesBetaHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBatchRequest' responses: '200': description: OK headers: x-request-id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Batch' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '403': $ref: '#/components/responses/ForbiddenResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: parameters: BatchesBetaHeader: in: header name: Exa-Beta schema: type: string enum: - batches-2026-06-06 description: Required beta token for the Batch API. required: true description: Required beta token for the Batch API. schemas: CreateBatchRequest: type: object properties: requests: minItems: 1 type: array items: $ref: '#/components/schemas/BatchRequestItem' description: >- The requests to enqueue. Each `customId` must be unique within the batch. metadata: type: object propertyNames: type: string additionalProperties: type: string description: Caller-provided metadata stored with the batch. required: - requests Batch: type: object properties: id: type: string description: Batch ID. New batch IDs are returned with the `batch_` prefix. object: type: string const: batch description: The object type, always `batch`. status: $ref: '#/components/schemas/BatchStatus' requestCounts: $ref: '#/components/schemas/BatchRequestCounts' createdAt: type: string format: date-time description: When the batch was created. expiresAt: anyOf: - type: string format: date-time - type: 'null' description: When the batch expires, or `null` if it does not expire. format: date-time endedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the batch reached a terminal status, or `null` while it is still running. format: date-time resultsUrl: anyOf: - type: string - type: 'null' description: >- Short-lived download URL for the batch results file (JSONL), or `null` until the batch completes. Fetch it directly, without an API key. Retrieve the batch again for a fresh URL after it expires. metadata: type: object propertyNames: type: string additionalProperties: type: string description: Caller-provided key-value metadata for your own tracking. required: - id - object - status - requestCounts - createdAt - expiresAt - endedAt - resultsUrl - metadata additionalProperties: false BatchRequestItem: type: object properties: customId: type: string minLength: 1 maxLength: 64 description: >- Your unique handle for this request; keys the result and must be unique in the batch. method: type: string const: POST description: HTTP method of the batched request. POST-only in v1. url: type: string enum: - /search - /agent/runs description: Target API route for the request. body: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' description: >- Request body for the target route. Must be a JSON object; `stream: true` is not allowed. required: - customId - method - url - body BatchStatus: type: string enum: - in_progress - completed - cancelling - cancelled - expired description: Lifecycle status of the batch. BatchRequestCounts: type: object properties: total: type: integer minimum: 0 description: Total requests in the batch. completed: type: integer minimum: 0 description: Requests that have completed successfully. failed: type: integer minimum: 0 description: Requests that have failed. required: - total - completed - failed additionalProperties: false ErrorResponse: type: object properties: requestId: type: string description: Unique identifier for the request. error: type: string description: Human-readable message describing the error. tag: type: string description: >- Machine-readable error tag identifying the failure. The set of tags is open-ended: new tags may be added at any time, so treat unrecognized tags as a generic error of the response's HTTP status. Known tags are listed as examples. required: - requestId - error - tag additionalProperties: false description: Standard error envelope returned by the Exa API for failed requests. JsonValue: description: Any JSON value. oneOf: - type: 'null' - type: boolean - type: number - type: string - type: array items: $ref: '#/components/schemas/JsonValue' - type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' headers: XRequestId: description: >- Unique identifier for the request. Matches the `requestId` field returned in response bodies that carry one. schema: type: string responses: BadRequestResponse: description: The request body or query parameters failed validation. headers: x-request-id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnauthorizedResponse: description: The API key is missing or invalid. headers: x-request-id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ForbiddenResponse: description: >- The team is not permitted to use this endpoint (`TEAM_BLOCKED`), or the feature is not enabled for it (`FEATURE_DISABLED`). headers: x-request-id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerErrorResponse: description: An unexpected error occurred while processing the request. headers: x-request-id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: apiKey: type: apiKey name: x-api-key in: header description: >- Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer . bearer: type: http scheme: bearer description: >- Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer . ````