> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Databox API reference

> API reference for the Databox plugin in Corsair: every `databox.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Auth

### validateKey

`auth.validateKey`

Check that the configured API key is valid; a setup or health check that reads nothing else

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.auth.validateKey({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `valid` | `true` | Yes | — |

***

## Dashboards

### list

`dashboards.list`

List dashboards with their tags and the integrations they use

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.dashboards.list({ search: 'sales' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search` | `string` | No | Search filter. |
| `page` | `number` | No | Zero-based page number. |
| `pageSize` | `number` | No | Maximum items per page; the docs example uses 100. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `dashboards` | `object[]` | Yes | — |
| `page` | `number` | Yes | — |
| `pageSize` | `number` | Yes | — |
| `totalItems` | `number \| null` | No | — |
| `nextPage` | `number \| null` | Yes | The next zero-based page while more items remain; null on the last page. |

> [accordion] dashboards full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   tags?: string[] | null,
>   integrationKeys?: string[] | null
> }[]
> ```

***

## Datasets

### create

`datasets.create`

Create a dataset in a data source with column definitions and an optional primary key that makes re-ingested records overwrite

**Risk:** `write`

```ts theme={null}
await corsair.databox.api.datasets.create({ name: 'Transactions', dataSourceId: 1234567, primaryKey: ['transaction_id'], schema: [{ id: 'transaction_id', dataType: 'string' }, { id: 'amount', dataType: 'number' }, { id: 'occurred_at', dataType: 'datetime' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Display name, such as Transactions. |
| `dataSourceId` | `number` | Yes | The data source that holds the dataset. |
| `primaryKey` | `string[]` | No | Column identifiers that make a record unique; re-ingesting a matching record overwrites it instead of appending. |
| `schema` | `object[]` | Yes | Column definitions for the dataset. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |
| `idempotencyKey` | `string` | No | A UUID, sent as Idempotency-Key; Databox rejects any other value with a 400 and returns the original response for the same key within 24 hours. |

> [accordion] schema full type
>
> ```ts theme={null}
> {
>   id: string,
>   dataType: datetime | number | string
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `dataset` | `object` | Yes | — |

> [accordion] dataset full type
>
> ```ts theme={null}
> {
>   id: number,
>   type?: string | null,
>   dataSourceId?: number | null,
>   name?: string | null,
>   timezone?: string | null,
>   ingestionSupported?: boolean | null,
>   statusInfo?: {
>     status?: string | null,
>     statusCode?: string | null,
>     errorType?: string | null,
>     reason?: string | null,
>     description?: string | null,
>     userAction?: string | null
>   } | null,
>   syncInfo?: {
>     status?: string | null,
>     type?: string | null,
>     initiatedAt?: string | null,
>     lastSuccessfulSyncAt?: string | null
>   } | null,
>   verificationInfo?: {
>     isVerified?: boolean | null
>   } | null,
>   ingestionInfo?: {
>     lastStatus?: string | null,
>     lastIngestionAt?: string | null
>   } | null,
>   createdAt?: string | null,
>   lastActivityAt?: string | null
> }
> ```

***

### get

`datasets.get`

Read one dataset with its status, sync and verification info

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.datasets.get({ id: 2345678 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | The dataset to read. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `dataset` | `object` | Yes | — |

> [accordion] dataset full type
>
> ```ts theme={null}
> {
>   id: number,
>   type?: string | null,
>   dataSourceId?: number | null,
>   name?: string | null,
>   timezone?: string | null,
>   ingestionSupported?: boolean | null,
>   statusInfo?: {
>     status?: string | null,
>     statusCode?: string | null,
>     errorType?: string | null,
>     reason?: string | null,
>     description?: string | null,
>     userAction?: string | null
>   } | null,
>   syncInfo?: {
>     status?: string | null,
>     type?: string | null,
>     initiatedAt?: string | null,
>     lastSuccessfulSyncAt?: string | null
>   } | null,
>   verificationInfo?: {
>     isVerified?: boolean | null
>   } | null,
>   ingestionInfo?: {
>     lastStatus?: string | null,
>     lastIngestionAt?: string | null
>   } | null,
>   createdAt?: string | null,
>   lastActivityAt?: string | null
> }
> ```

***

### getIngestion

`datasets.getIngestion`

Read one ingestion's status and record counts: how many records were appended, overwritten or rejected

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.datasets.getIngestion({ id: 2345678, ingestionId: 'a4283796-bfde-42cf-aa65-1830d6692966' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | The dataset the ingestion ran against. |
| `ingestionId` | `string` | Yes | The ingestion ID returned by datasets.ingestData. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ingestion` | `object` | Yes | — |

> [accordion] ingestion full type
>
> ```ts theme={null}
> {
>   id: string,
>   initiatedAt?: string | null,
>   status?: string | null,
>   duration?: number | null,
>   initiatedBy?: {
>     id?: number | null,
>     name?: string | null
>   } | null,
>   summary?: {
>     ingestion?: {
>       receivedRecordCount?: number | null,
>       appendedRecordCount?: number | null,
>       overwrittenRecordCount?: number | null,
>       rejectedRecordCount?: number | null
>     } | null,
>     dataset?: {
>       columnCount?: number | null,
>       rowCount?: number | null,
>       size?: number | null
>     } | null
>   } | null,
>   errors?: Record<string, any>[] | null
> }
> ```

***

### ingestData

`datasets.ingestData`

Submit up to 500 records for ingestion; the response carries an ingestionId to poll in datasets.getIngestion

**Risk:** `write`

```ts theme={null}
await corsair.databox.api.datasets.ingestData({ id: 2345678, records: [{ transaction_id: 'T-10024', amount: 249, occurred_at: '2026-09-18T09:12:00+00:00' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | The dataset to ingest into. |
| `records` | `Record<string, string \| number \| boolean \| null>[]` | Yes | Records keyed by column ID; at most 500 rows per request. With a primaryKey, matching records overwrite. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |
| `idempotencyKey` | `string` | No | A UUID, sent as Idempotency-Key; Databox rejects any other value with a 400 and returns the original response for the same key within 24 hours. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ingestionId` | `string` | Yes | Pass with the dataset ID to datasets.getIngestion to poll. |
| `status` | `string \| null` | No | — |
| `message` | `string \| null` | No | — |

***

### list

`datasets.list`

List datasets, optionally filtered by data source or type (API-created or merged), with search and paging

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.datasets.list({ dataSourceId: 1234567, type: 'dataset' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `dataSourceId` | `number` | No | Only datasets in this data source. |
| `type` | `dataset \| mergedDataset` | No | dataset is API-created; mergedDataset combines several. |
| `search` | `string` | No | Search term. |
| `sortBy` | `string` | No | Field to sort by. |
| `sortOrder` | `string` | No | Sort direction, such as asc or desc. |
| `page` | `number` | No | Zero-based page number. |
| `pageSize` | `number` | No | Maximum items per page; the docs example uses 100. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `datasets` | `object[]` | Yes | — |
| `page` | `number` | Yes | — |
| `pageSize` | `number` | Yes | — |
| `totalItems` | `number \| null` | No | — |
| `nextPage` | `number \| null` | Yes | The next zero-based page while more items remain; null on the last page. |

> [accordion] datasets full type
>
> ```ts theme={null}
> {
>   id: number,
>   type?: string | null,
>   dataSourceId?: number | null,
>   name?: string | null,
>   timezone?: string | null,
>   ingestionSupported?: boolean | null,
>   statusInfo?: {
>     status?: string | null,
>     statusCode?: string | null,
>     errorType?: string | null,
>     reason?: string | null,
>     description?: string | null,
>     userAction?: string | null
>   } | null,
>   syncInfo?: {
>     status?: string | null,
>     type?: string | null,
>     initiatedAt?: string | null,
>     lastSuccessfulSyncAt?: string | null
>   } | null,
>   verificationInfo?: {
>     isVerified?: boolean | null
>   } | null,
>   ingestionInfo?: {
>     lastStatus?: string | null,
>     lastIngestionAt?: string | null
>   } | null,
>   createdAt?: string | null,
>   lastActivityAt?: string | null
> }[]
> ```

***

### listData

`datasets.listData`

Read a page of a dataset's records with the column schema; records are keyed by column ID

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.datasets.listData({ id: 2345678, page: 0, pageSize: 100 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | The dataset whose records to read. |
| `sortBy` | `string` | No | Column to sort by. |
| `sortOrder` | `string` | No | Sort direction, such as asc or desc. |
| `page` | `number` | No | Zero-based page number. |
| `pageSize` | `number` | No | Maximum items per page; the docs example uses 100. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `records` | `Record<string, string \| number \| boolean \| null>[]` | Yes | — |
| `schema` | `object[] \| null` | No | — |
| `page` | `number` | Yes | — |
| `pageSize` | `number` | Yes | — |
| `totalItems` | `number \| null` | No | — |
| `nextPage` | `number \| null` | Yes | The next zero-based page while more items remain; null on the last page. |
| `lastUpdatedAt` | `string \| null` | No | — |

> [accordion] schema full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   displayName?: string | null,
>   dataType?: string | null,
>   order?: number | null,
>   visible?: boolean | null
> }[] | null
> ```

***

## Data Sources

### create

`dataSources.create`

Create a data source for pushing custom data through the API; only a name is required

**Risk:** `write`

```ts theme={null}
await corsair.databox.api.dataSources.create({ name: 'Sales', timezone: 'Europe/Ljubljana', idempotencyKey: '3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0d' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Display name, such as Sales. |
| `timezone` | `string` | No | IANA timezone identifier, such as Europe/Ljubljana. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |
| `idempotencyKey` | `string` | No | A UUID, sent as Idempotency-Key; Databox rejects any other value with a 400 and returns the original response for the same key within 24 hours. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `dataSource` | `object` | Yes | — |

> [accordion] dataSource full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   integrationKey?: string | null,
>   timezone?: string | null,
>   statusInfo?: {
>     status?: string | null,
>     statusCode?: string | null,
>     errorType?: string | null,
>     reason?: string | null,
>     description?: string | null,
>     userAction?: string | null
>   } | null,
>   connectionId?: number | null,
>   managedBy?: {
>     id?: number | null,
>     name?: string | null
>   } | null,
>   createdAt?: string | null,
>   lastActivityAt?: string | null,
>   syncInterval?: number | null
> }
> ```

***

### delete

`dataSources.delete`

Permanently delete a data source and every dataset and record it holds; this cannot be undone

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.databox.api.dataSources.delete({ id: 1234567 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | The data source to delete, along with every dataset and record it holds. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `message` | `string \| null` | No | Databox's human-readable outcome note. |

***

### get

`dataSources.get`

Read one data source, including its status and sync interval

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.dataSources.get({ id: 1234567 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | The data source to read. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `dataSource` | `object` | Yes | — |

> [accordion] dataSource full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   integrationKey?: string | null,
>   timezone?: string | null,
>   statusInfo?: {
>     status?: string | null,
>     statusCode?: string | null,
>     errorType?: string | null,
>     reason?: string | null,
>     description?: string | null,
>     userAction?: string | null
>   } | null,
>   connectionId?: number | null,
>   managedBy?: {
>     id?: number | null,
>     name?: string | null
>   } | null,
>   createdAt?: string | null,
>   lastActivityAt?: string | null,
>   syncInterval?: number | null
> }
> ```

***

### list

`dataSources.list`

List the data sources in the organization, with search, connection filter, sorting and paging

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.dataSources.list({ page: 0, pageSize: 50 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search` | `string` | No | Filter by keyword. |
| `connectionId` | `number` | No | Only data sources with this connection. |
| `sortBy` | `string` | No | Field to sort by. |
| `sortOrder` | `string` | No | Sort direction, such as asc or desc. |
| `page` | `number` | No | Zero-based page number. |
| `pageSize` | `number` | No | Maximum items per page; the docs example uses 100. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `dataSources` | `object[]` | Yes | — |
| `page` | `number` | Yes | — |
| `pageSize` | `number` | Yes | — |
| `totalItems` | `number \| null` | No | — |
| `nextPage` | `number \| null` | Yes | The next zero-based page while more items remain; null on the last page. |

> [accordion] dataSources full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   integrationKey?: string | null,
>   timezone?: string | null,
>   statusInfo?: {
>     status?: string | null,
>     statusCode?: string | null,
>     errorType?: string | null,
>     reason?: string | null,
>     description?: string | null,
>     userAction?: string | null
>   } | null,
>   connectionId?: number | null,
>   managedBy?: {
>     id?: number | null,
>     name?: string | null
>   } | null,
>   createdAt?: string | null,
>   lastActivityAt?: string | null,
>   syncInterval?: number | null
> }[]
> ```

***

## Metrics

### getData

`metrics.getData`

Read a metric's values over a date range with granularity, dimension breakdowns and filters; may wait for a first sync (up to two minutes)

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.metrics.getData({ id: 'GoogleAnalytics4@sessions', dateRange: { from: '2026-06-01', to: '2026-06-30', granularity: 'daily' } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Metric ID, such as 'GoogleAnalytics4\@sessions', from metrics.list. |
| `sourceId` | `number` | No | Restrict the metric to one data source or dataset. |
| `dateRange` | `object` | Yes | — |
| `dimensionIds` | `string[]` | No | Dimension IDs to break the values down by; from the metric. |
| `filters` | `object` | No | — |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

> [accordion] dateRange full type
>
> ```ts theme={null}
> {
>   from: string,
>   to: string,
>   granularity: daily | weekly | monthly | quarterly | yearly | allTime
> }
> ```

> [accordion] filters full type
>
> ```ts theme={null}
> {
>   logicalOperator?: and | or,
>   conditions: {
>     type?: dimension | unit,
>     field: string,
>     operator: ANY_OF | NONE_OF | EQ | NEQ | CONTAINS | NOT_CONTAINS,
>     values?: string[]
>   }[]
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `metric` | `object \| null` | Yes | — |
| `dataPoints` | `object[]` | Yes | — |
| `syncInfo` | `object \| null` | No | — |

> [accordion] metric full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null,
>   sourceId?: number | null
> } | null
> ```

> [accordion] dataPoints full type
>
> ```ts theme={null}
> {
>   date?: string | null,
>   value: number | null,
>   dimensions?: Record<string, any> | null
> }[]
> ```

> [accordion] syncInfo full type
>
> ```ts theme={null}
> {
>   status?: string | null,
>   lastSyncedAt?: string | null,
>   message?: string | null
> } | null
> ```

***

### list

`metrics.list`

List the organization's metrics with their dimensions, optionally filtered by source or name

**Risk:** `read`

```ts theme={null}
await corsair.databox.api.metrics.list({ sourceId: 1234567 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `sourceId` | `number` | No | Only metrics of this data source or dataset. |
| `search` | `string` | No | Search metric names. |
| `page` | `number` | No | Zero-based page number. |
| `pageSize` | `number` | No | Maximum items per page; the docs example uses 100. |
| `accountId` | `number` | No | Sent as x-account-id to act on one account of the organization instead of the organization tied to the key. Only for organizations with accounts enabled. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `metrics` | `object[]` | Yes | — |
| `page` | `number` | Yes | — |
| `pageSize` | `number` | Yes | — |
| `totalItems` | `number \| null` | No | — |
| `nextPage` | `number \| null` | Yes | The next zero-based page while more items remain; null on the last page. |

> [accordion] metrics full type
>
> ```ts theme={null}
> {
>   id: string,
>   name?: string | null,
>   description?: string | null,
>   sourceId?: number | null,
>   dimensions?: {
>     id?: string | null,
>     displayName?: string | null
>   }[] | null,
>   supportsDrilldown?: boolean | null,
>   verificationInfo?: {
>     isVerified?: boolean | null
>   } | null
> }[]
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.