Create a batch

curl --request POST \
  --url https://api.exa.ai/batches \
  --header 'Content-Type: application/json' \
  --header 'Exa-Beta: <exa-beta>' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "requests": [
    {
      "customId": "row-1",
      "method": "POST",
      "url": "/search",
      "body": {
        "query": "Latest AI infrastructure funding rounds"
      }
    },
    {
      "customId": "row-2",
      "method": "POST",
      "url": "/agent/runs",
      "body": {
        "query": "Summarize this week's vector database launches"
      }
    }
  ],
  "metadata": {
    "project": "weekly-digest"
  }
}
EOF

import requests

url = "https://api.exa.ai/batches"

payload = {
    "requests": [
        {
            "customId": "row-1",
            "method": "POST",
            "url": "/search",
            "body": { "query": "Latest AI infrastructure funding rounds" }
        },
        {
            "customId": "row-2",
            "method": "POST",
            "url": "/agent/runs",
            "body": { "query": "Summarize this week's vector database launches" }
        }
    ],
    "metadata": { "project": "weekly-digest" }
}
headers = {
    "Exa-Beta": "<exa-beta>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Exa-Beta': '<exa-beta>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    requests: [
      {
        customId: 'row-1',
        method: 'POST',
        url: '/search',
        body: JSON.stringify({query: 'Latest AI infrastructure funding rounds'})
      },
      {
        customId: 'row-2',
        method: 'POST',
        url: '/agent/runs',
        body: JSON.stringify({query: 'Summarize this week\'s vector database launches'})
      }
    ],
    metadata: {project: 'weekly-digest'}
  })
};

fetch('https://api.exa.ai/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8",
  "object": "batch",
  "status": "in_progress",
  "requestCounts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  },
  "createdAt": "2026-06-06T12:00:00.000Z",
  "expiresAt": "2026-06-13T12:00:00.000Z",
  "endedAt": null,
  "resultsUrl": null,
  "metadata": {
    "project": "weekly-digest"
  }
}

{
  "requestId": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "error": "Invalid request body: query: Invalid input: expected string, received undefined",
  "tag": "INVALID_REQUEST_BODY"
}

{
  "requestId": "f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2",
  "error": "Invalid API key",
  "tag": "INVALID_API_KEY"
}

{
  "requestId": "9b1d3f5e7a0c2e4b6d8f0a2c4e6b8d0f",
  "error": "Sorry, we encountered an error while processing your request. Please try again later",
  "tag": "DEFAULT_ERROR"
}

POST

batches

Create a batch

curl --request POST \
  --url https://api.exa.ai/batches \
  --header 'Content-Type: application/json' \
  --header 'Exa-Beta: <exa-beta>' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "requests": [
    {
      "customId": "row-1",
      "method": "POST",
      "url": "/search",
      "body": {
        "query": "Latest AI infrastructure funding rounds"
      }
    },
    {
      "customId": "row-2",
      "method": "POST",
      "url": "/agent/runs",
      "body": {
        "query": "Summarize this week's vector database launches"
      }
    }
  ],
  "metadata": {
    "project": "weekly-digest"
  }
}
EOF

import requests

url = "https://api.exa.ai/batches"

payload = {
    "requests": [
        {
            "customId": "row-1",
            "method": "POST",
            "url": "/search",
            "body": { "query": "Latest AI infrastructure funding rounds" }
        },
        {
            "customId": "row-2",
            "method": "POST",
            "url": "/agent/runs",
            "body": { "query": "Summarize this week's vector database launches" }
        }
    ],
    "metadata": { "project": "weekly-digest" }
}
headers = {
    "Exa-Beta": "<exa-beta>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Exa-Beta': '<exa-beta>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    requests: [
      {
        customId: 'row-1',
        method: 'POST',
        url: '/search',
        body: JSON.stringify({query: 'Latest AI infrastructure funding rounds'})
      },
      {
        customId: 'row-2',
        method: 'POST',
        url: '/agent/runs',
        body: JSON.stringify({query: 'Summarize this week\'s vector database launches'})
      }
    ],
    metadata: {project: 'weekly-digest'}
  })
};

fetch('https://api.exa.ai/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8",
  "object": "batch",
  "status": "in_progress",
  "requestCounts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  },
  "createdAt": "2026-06-06T12:00:00.000Z",
  "expiresAt": "2026-06-13T12:00:00.000Z",
  "endedAt": null,
  "resultsUrl": null,
  "metadata": {
    "project": "weekly-digest"
  }
}

{
  "requestId": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "error": "Invalid request body: query: Invalid input: expected string, received undefined",
  "tag": "INVALID_REQUEST_BODY"
}

{
  "requestId": "f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2",
  "error": "Invalid API key",
  "tag": "INVALID_API_KEY"
}

{
  "requestId": "9b1d3f5e7a0c2e4b6d8f0a2c4e6b8d0f",
  "error": "Sorry, we encountered an error while processing your request. Please try again later",
  "tag": "DEFAULT_ERROR"
}

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 for the end-to-end workflow.

Get your Exa API key

Authorizations

x-api-key

string

header

required

Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer .

Headers

Exa-Beta

enum<string>

required

Required beta token for the Batch API.

Available options:

batches-2026-06-06

Body

application/json

requests

object[]

required

The requests to enqueue. Each customId must be unique within the batch.

Minimum array length: 1

Show child attributes

metadata

object

Caller-provided metadata stored with the batch.

Show child attributes

Example:

{
  "slack_channel_id": "C123ABC",
  "slack_thread_id": "1745444400.123456",
  "user_id": "U123ABC"
}

Response

string

required

Batch ID. New batch IDs are returned with the batch_ prefix.

Example:

"batch_01j7x9v0m2n4p6q8r0s2t4v6w8"

object

string

required

The object type, always batch.

Allowed value: "batch"

status

enum<string>

required

Lifecycle status of the batch.

Available options:

in_progress,

completed,

cancelling,

cancelled,

expired

requestCounts

object

required

Show child attributes

createdAt

string<date-time>

required

When the batch was created.

expiresAt

string<date-time>

required

When the batch expires, or null if it does not expire.

endedAt

string<date-time>

required

When the batch reached a terminal status, or null while it is still running.

resultsUrl

string | null

required

Short-lived presigned download URL for the batch results file (JSONL), or null until the batch completes. This is a direct object-store download link, not an API route; fetch it as-is and re-fetch the batch to mint a fresh URL once it expires.

metadata

object

required

Caller-provided key-value metadata for your own tracking.

Show child attributes

Example:

{
  "slack_channel_id": "C123ABC",
  "slack_thread_id": "1745444400.123456",
  "user_id": "U123ABC"
}

Search

Agent

Websets

Monitors

Batch

Team Management

Create a batch

Get your Exa API key

Authorizations

Headers

Body

Response