---
title: Batches
url: https://anyrow.ai/docs/api/batches
canonical_url: https://anyrow.ai/docs/api/batches
---

# Batches

A batch is one extraction run over one or more files: its status, rows and downloads.

- [List batches](https://anyrow.ai/docs/api/batches/list.md): `GET /v1/projects/{project_id}/batches`
- [Get batch](https://anyrow.ai/docs/api/batches/get.md): `GET /v1/projects/{project_id}/batches/{batch_id}`
- [Download batch CSV](https://anyrow.ai/docs/api/batches/download-csv.md): `GET /v1/projects/{project_id}/batches/{batch_id}/download/csv`
- [Download batch JSON](https://anyrow.ai/docs/api/batches/download-json.md): `GET /v1/projects/{project_id}/batches/{batch_id}/download/json`
- [Download batch XLSX](https://anyrow.ai/docs/api/batches/download-xlsx.md): `GET /v1/projects/{project_id}/batches/{batch_id}/download/xlsx`

## The Batch object

- `created_at` (integer, required): At least 0.
- `updated_at` (integer, required): At least 0.
- `id` (string, required): 1 to 48 characters.
- `project_id` (string, required): 1 to 48 characters.
- `table_id` (string, required, nullable): 1 to 48 characters.
- `actor_type` (string, required): One of `user`, `api_key`.
- `actor_id` (string, required): Up to 36 characters.
- `schema_json` (object, required)
  - `columns` (array of objects, required): 1 to 50 items.
    - `description` (string, optional, nullable): Up to 256 characters.
    - `instruction` (string, optional, nullable): Up to 512 characters.
    - `name` (string, required): 1 to 64 characters. Matches `^[\w\s.-]+$`.
    - `type` (string, required): One of `array`, `boolean`, `currency`, `date`, `email`, `enum`, `multi_select`, `number`, `string`, `text`, `url`. Defaults to `string`.
  - `instruction` (string, optional, nullable): Up to 512 characters.
  - `strictness` (string, required): One of `strict`, `balanced`, `flexible`. Defaults to `strict`.
- `insert_mode` (string, required, nullable): One of `append`, `dedup`, `merge`, `replace`.
- `status` (string, required): One of `uploading`, `processing`, `merging`, `complete`, `partial`, `failed`.
- `file_count` (integer, required): At least 1.
- `files_done` (integer, required): At least 0.
- `current_file` (string, required, nullable): Up to 255 characters.
- `csv_key` (string, required, nullable): Up to 512 characters.
- `json_key` (string, required, nullable): Up to 512 characters.
- `xlsx_key` (string, required, nullable): Up to 512 characters.
- `total_rows` (integer, required, nullable): At least 0.
- `confidence` (number, required, nullable)
- `duration_ms` (integer, required, nullable): At least 0.
- `error` (string, required, nullable): Up to 2048 characters.
- `extractions` (array of objects, optional)
  - `created_at` (integer, required): At least 0.
  - `id` (string, required): 1 to 48 characters.
  - `batch_id` (string, required): 1 to 48 characters.
  - `table_id` (string, required, nullable): 1 to 48 characters.
  - `file_key` (string, required): Up to 512 characters.
  - `file_name` (string, required): Up to 255 characters.
  - `file_type` (string, required, nullable): One of `text_pdf`, `scanned`, `image`, `text`, `document`, `unknown`.
  - `file_checksum` (string, required, nullable): Up to 64 characters.
  - `status` (string, required): One of `pending`, `processing`, `complete`, `failed`.
  - `rows_key` (string, required, nullable): Up to 512 characters.
  - `row_count` (integer, required, nullable): At least 0.
  - `confidence` (number, required, nullable)
  - `error` (string, required, nullable): Up to 2048 characters.

```json
{
  "created_at": 1711468800000,
  "updated_at": 1711468800000,
  "id": "batch_01h5a3g8k9m2n4p6q8r0t2v4x6",
  "project_id": "string",
  "table_id": "string",
  "actor_type": "user",
  "actor_id": "string",
  "schema_json": {
    "columns": [
      {
        "description": "string",
        "instruction": "string",
        "name": "string",
        "type": "string"
      }
    ],
    "instruction": "string",
    "strictness": "strict"
  },
  "insert_mode": "append",
  "status": "uploading",
  "file_count": 42,
  "files_done": 42,
  "current_file": "string",
  "csv_key": "string",
  "json_key": "string",
  "xlsx_key": "string",
  "total_rows": 42,
  "confidence": 0.5,
  "duration_ms": 42,
  "error": "string",
  "extractions": [
    {
      "created_at": 1711468800000,
      "id": "extr_01h5a3g8k9m2n4p6q8r0t2v4x6",
      "batch_id": "string",
      "table_id": "string",
      "file_key": "string",
      "file_name": "string",
      "file_type": "text_pdf",
      "file_checksum": "string",
      "status": "pending",
      "rows_key": "string",
      "row_count": 42,
      "confidence": 0.5,
      "error": "string"
    }
  ]
}
```

## List batches

`GET /v1/projects/{project_id}/batches`

Authentication: `Authorization: ApiKey {your_api_key}`.

### Path parameters

- `project_id` (string, required)

### Query parameters

- `cursor` (string, optional): Opaque cursor for forward pagination. Pass the nextCursor from the previous response with the same order. Takes precedence over page when both are sent.
- `page` (integer, optional): 1-based page number for offset pagination. Ignored when cursor is present. At least 1.
- `order` (string, optional): Sort keys, comma-separated, each `field[.asc|.desc][.nullsfirst|.nullslast]`; at most 3. Sortable: created_at, status, total_rows. Default: created_at.desc. Nulls sort last ascending and first descending unless stated. Matches `^(?:created_at|status|total_rows)(?:\.(?:asc|desc))?(?:\.(?:nullsfirst|nullslast))?(?:,(?:created_at|status|total_rows)(?:\.(?:asc|desc))?(?:\.(?:nullsfirst|nullslast))?){0,2}$`.
- `limit` (integer, optional): Maximum number of items per page. Defaults to 20, capped by the endpoint's maxLimit. Defaults to `20`. Between 1 and 100.
- `status` (string, optional): One of `uploading`, `processing`, `merging`, `complete`, `partial`, `failed`.

### Returns

200 `application/json`.

- `count` (integer, required): At least 0.
- `hasMore` (boolean, required)
- `limit` (integer, required): At least 1.
- `nextCursor` (string, required, nullable)
- `page` (integer, required, nullable): At least 1.
- `batches` (array of objects, required)
  - `created_at` (integer, required): At least 0.
  - `updated_at` (integer, required): At least 0.
  - `id` (string, required): 1 to 48 characters.
  - `project_id` (string, required): 1 to 48 characters.
  - `table_id` (string, required, nullable): 1 to 48 characters.
  - `actor_type` (string, required): One of `user`, `api_key`.
  - `actor_id` (string, required): Up to 36 characters.
  - `schema_json` (object, required)
    - `columns` (array of objects, required): 1 to 50 items.
      - `description` (string, optional, nullable): Up to 256 characters.
      - `instruction` (string, optional, nullable): Up to 512 characters.
      - `name` (string, required): 1 to 64 characters. Matches `^[\w\s.-]+$`.
      - `type` (string, required): One of `array`, `boolean`, `currency`, `date`, `email`, `enum`, `multi_select`, `number`, `string`, `text`, `url`. Defaults to `string`.
    - `instruction` (string, optional, nullable): Up to 512 characters.
    - `strictness` (string, required): One of `strict`, `balanced`, `flexible`. Defaults to `strict`.
  - `insert_mode` (string, required, nullable): One of `append`, `dedup`, `merge`, `replace`.
  - `status` (string, required): One of `uploading`, `processing`, `merging`, `complete`, `partial`, `failed`.
  - `file_count` (integer, required): At least 1.
  - `files_done` (integer, required): At least 0.
  - `current_file` (string, required, nullable): Up to 255 characters.
  - `csv_key` (string, required, nullable): Up to 512 characters.
  - `json_key` (string, required, nullable): Up to 512 characters.
  - `xlsx_key` (string, required, nullable): Up to 512 characters.
  - `total_rows` (integer, required, nullable): At least 0.
  - `confidence` (number, required, nullable)
  - `duration_ms` (integer, required, nullable): At least 0.
  - `error` (string, required, nullable): Up to 2048 characters.

### Errors

- 404: `not_found`

Errors every endpoint can return: [Errors](https://anyrow.ai/docs/api/errors.md).

### Request

```ts title="Node.js"
import { AnyrowSDK } from "@anyrow/sdk"

const anyrow = new AnyrowSDK({
  baseURL: "https://api.anyrow.ai",
  headers: { Authorization: `ApiKey ${process.env.ANYROW_API_KEY}` },
})

const { data, error } = await anyrow.batch.list({
  params: {
    project_id: "{project_id}"
  },
})
```

```bash title="cURL"
curl 'https://api.anyrow.ai/v1/projects/{project_id}/batches' \
  -H 'Authorization: ApiKey {your_api_key}'
```

```js title="JavaScript"
const response = await fetch("https://api.anyrow.ai/v1/projects/{project_id}/batches", {
  headers: {
    Authorization: "ApiKey {your_api_key}",
  },
})
const data = await response.json()
```

```python title="Python"
import requests

response = requests.get(
    "https://api.anyrow.ai/v1/projects/{project_id}/batches",
    headers={
        "Authorization": "ApiKey {your_api_key}",
    },
)
print(response.json())
```

### Response

```json title="200"
{
  "count": 0,
  "hasMore": true,
  "limit": 1,
  "nextCursor": "string",
  "page": 1,
  "batches": [
    {
      "created_at": 1711468800000,
      "updated_at": 1711468800000,
      "id": "batch_01h5a3g8k9m2n4p6q8r0t2v4x6",
      "project_id": "string",
      "table_id": "string",
      "actor_type": "user",
      "actor_id": "string",
      "schema_json": {
        "columns": [
          {
            "description": "string",
            "instruction": "string",
            "name": "string",
            "type": "string"
          }
        ],
        "instruction": "string",
        "strictness": "strict"
      },
      "insert_mode": "append",
      "status": "uploading",
      "file_count": 42,
      "files_done": 42,
      "current_file": "string",
      "csv_key": "string",
      "json_key": "string",
      "xlsx_key": "string",
      "total_rows": 42,
      "confidence": 0.5,
      "duration_ms": 42,
      "error": "string"
    }
  ]
}
```

## Get batch

`GET /v1/projects/{project_id}/batches/{batch_id}`

Authentication: `Authorization: ApiKey {your_api_key}`.

### Path parameters

- `project_id` (string, required)
- `batch_id` (string, required)

### Returns

200 `application/json`.

- `created_at` (integer, required): At least 0.
- `updated_at` (integer, required): At least 0.
- `id` (string, required): 1 to 48 characters.
- `project_id` (string, required): 1 to 48 characters.
- `table_id` (string, required, nullable): 1 to 48 characters.
- `actor_type` (string, required): One of `user`, `api_key`.
- `actor_id` (string, required): Up to 36 characters.
- `schema_json` (object, required)
  - `columns` (array of objects, required): 1 to 50 items.
    - `description` (string, optional, nullable): Up to 256 characters.
    - `instruction` (string, optional, nullable): Up to 512 characters.
    - `name` (string, required): 1 to 64 characters. Matches `^[\w\s.-]+$`.
    - `type` (string, required): One of `array`, `boolean`, `currency`, `date`, `email`, `enum`, `multi_select`, `number`, `string`, `text`, `url`. Defaults to `string`.
  - `instruction` (string, optional, nullable): Up to 512 characters.
  - `strictness` (string, required): One of `strict`, `balanced`, `flexible`. Defaults to `strict`.
- `insert_mode` (string, required, nullable): One of `append`, `dedup`, `merge`, `replace`.
- `status` (string, required): One of `uploading`, `processing`, `merging`, `complete`, `partial`, `failed`.
- `file_count` (integer, required): At least 1.
- `files_done` (integer, required): At least 0.
- `current_file` (string, required, nullable): Up to 255 characters.
- `csv_key` (string, required, nullable): Up to 512 characters.
- `json_key` (string, required, nullable): Up to 512 characters.
- `xlsx_key` (string, required, nullable): Up to 512 characters.
- `total_rows` (integer, required, nullable): At least 0.
- `confidence` (number, required, nullable)
- `duration_ms` (integer, required, nullable): At least 0.
- `error` (string, required, nullable): Up to 2048 characters.
- `extractions` (array of objects, optional)
  - `created_at` (integer, required): At least 0.
  - `id` (string, required): 1 to 48 characters.
  - `batch_id` (string, required): 1 to 48 characters.
  - `table_id` (string, required, nullable): 1 to 48 characters.
  - `file_key` (string, required): Up to 512 characters.
  - `file_name` (string, required): Up to 255 characters.
  - `file_type` (string, required, nullable): One of `text_pdf`, `scanned`, `image`, `text`, `document`, `unknown`.
  - `file_checksum` (string, required, nullable): Up to 64 characters.
  - `status` (string, required): One of `pending`, `processing`, `complete`, `failed`.
  - `rows_key` (string, required, nullable): Up to 512 characters.
  - `row_count` (integer, required, nullable): At least 0.
  - `confidence` (number, required, nullable)
  - `error` (string, required, nullable): Up to 2048 characters.

### Errors

- 404: `batch_not_found`, `not_found`

Errors every endpoint can return: [Errors](https://anyrow.ai/docs/api/errors.md).

### Request

```ts title="Node.js"
import { AnyrowSDK } from "@anyrow/sdk"

const anyrow = new AnyrowSDK({
  baseURL: "https://api.anyrow.ai",
  headers: { Authorization: `ApiKey ${process.env.ANYROW_API_KEY}` },
})

const { data, error } = await anyrow.batch.get({
  params: {
    project_id: "{project_id}",
    batch_id: "{batch_id}"
  },
})
```

```bash title="cURL"
curl 'https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}' \
  -H 'Authorization: ApiKey {your_api_key}'
```

```js title="JavaScript"
const response = await fetch("https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}", {
  headers: {
    Authorization: "ApiKey {your_api_key}",
  },
})
const data = await response.json()
```

```python title="Python"
import requests

response = requests.get(
    "https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}",
    headers={
        "Authorization": "ApiKey {your_api_key}",
    },
)
print(response.json())
```

### Response

```json title="200"
{
  "created_at": 1711468800000,
  "updated_at": 1711468800000,
  "id": "batch_01h5a3g8k9m2n4p6q8r0t2v4x6",
  "project_id": "string",
  "table_id": "string",
  "actor_type": "user",
  "actor_id": "string",
  "schema_json": {
    "columns": [
      {
        "description": "string",
        "instruction": "string",
        "name": "string",
        "type": "string"
      }
    ],
    "instruction": "string",
    "strictness": "strict"
  },
  "insert_mode": "append",
  "status": "uploading",
  "file_count": 42,
  "files_done": 42,
  "current_file": "string",
  "csv_key": "string",
  "json_key": "string",
  "xlsx_key": "string",
  "total_rows": 42,
  "confidence": 0.5,
  "duration_ms": 42,
  "error": "string",
  "extractions": [
    {
      "created_at": 1711468800000,
      "id": "extr_01h5a3g8k9m2n4p6q8r0t2v4x6",
      "batch_id": "string",
      "table_id": "string",
      "file_key": "string",
      "file_name": "string",
      "file_type": "text_pdf",
      "file_checksum": "string",
      "status": "pending",
      "rows_key": "string",
      "row_count": 42,
      "confidence": 0.5,
      "error": "string"
    }
  ]
}
```

## Download batch CSV

`GET /v1/projects/{project_id}/batches/{batch_id}/download/csv`

Authentication: `Authorization: ApiKey {your_api_key}`.

### Path parameters

- `project_id` (string, required)
- `batch_id` (string, required)

### Returns

No response body; the request succeeds or returns an error.

### Errors

- 404: `batch_not_found`, `not_found`

Errors every endpoint can return: [Errors](https://anyrow.ai/docs/api/errors.md).

### Request

```ts title="Node.js"
import { AnyrowSDK } from "@anyrow/sdk"

const anyrow = new AnyrowSDK({
  baseURL: "https://api.anyrow.ai",
  headers: { Authorization: `ApiKey ${process.env.ANYROW_API_KEY}` },
})

const { data, error } = await anyrow.batch.download.csv({
  params: {
    project_id: "{project_id}",
    batch_id: "{batch_id}"
  },
})
```

```bash title="cURL"
curl 'https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/csv' \
  -H 'Authorization: ApiKey {your_api_key}'
```

```js title="JavaScript"
const response = await fetch("https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/csv", {
  headers: {
    Authorization: "ApiKey {your_api_key}",
  },
})
const data = await response.json()
```

```python title="Python"
import requests

response = requests.get(
    "https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/csv",
    headers={
        "Authorization": "ApiKey {your_api_key}",
    },
)
print(response.json())
```

## Download batch JSON

`GET /v1/projects/{project_id}/batches/{batch_id}/download/json`

Authentication: `Authorization: ApiKey {your_api_key}`.

### Path parameters

- `project_id` (string, required)
- `batch_id` (string, required)

### Returns

No response body; the request succeeds or returns an error.

### Errors

- 404: `batch_not_found`, `not_found`

Errors every endpoint can return: [Errors](https://anyrow.ai/docs/api/errors.md).

### Request

```ts title="Node.js"
import { AnyrowSDK } from "@anyrow/sdk"

const anyrow = new AnyrowSDK({
  baseURL: "https://api.anyrow.ai",
  headers: { Authorization: `ApiKey ${process.env.ANYROW_API_KEY}` },
})

const { data, error } = await anyrow.batch.download.json({
  params: {
    project_id: "{project_id}",
    batch_id: "{batch_id}"
  },
})
```

```bash title="cURL"
curl 'https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/json' \
  -H 'Authorization: ApiKey {your_api_key}'
```

```js title="JavaScript"
const response = await fetch("https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/json", {
  headers: {
    Authorization: "ApiKey {your_api_key}",
  },
})
const data = await response.json()
```

```python title="Python"
import requests

response = requests.get(
    "https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/json",
    headers={
        "Authorization": "ApiKey {your_api_key}",
    },
)
print(response.json())
```

## Download batch XLSX

`GET /v1/projects/{project_id}/batches/{batch_id}/download/xlsx`

Authentication: `Authorization: ApiKey {your_api_key}`.

### Path parameters

- `project_id` (string, required)
- `batch_id` (string, required)

### Returns

No response body; the request succeeds or returns an error.

### Errors

- 404: `batch_not_found`, `not_found`

Errors every endpoint can return: [Errors](https://anyrow.ai/docs/api/errors.md).

### Request

```ts title="Node.js"
import { AnyrowSDK } from "@anyrow/sdk"

const anyrow = new AnyrowSDK({
  baseURL: "https://api.anyrow.ai",
  headers: { Authorization: `ApiKey ${process.env.ANYROW_API_KEY}` },
})

const { data, error } = await anyrow.batch.download.xlsx({
  params: {
    project_id: "{project_id}",
    batch_id: "{batch_id}"
  },
})
```

```bash title="cURL"
curl 'https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/xlsx' \
  -H 'Authorization: ApiKey {your_api_key}'
```

```js title="JavaScript"
const response = await fetch("https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/xlsx", {
  headers: {
    Authorization: "ApiKey {your_api_key}",
  },
})
const data = await response.json()
```

```python title="Python"
import requests

response = requests.get(
    "https://api.anyrow.ai/v1/projects/{project_id}/batches/{batch_id}/download/xlsx",
    headers={
        "Authorization": "ApiKey {your_api_key}",
    },
)
print(response.json())
```