Databox API reference

New to Corsair? See API access, authentication, and 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

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

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.

dashboards full type

{
  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

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.

schema full type

{
  id: string,
  dataType: datetime | number | string
}[]

Output

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

dataset full type

{
  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

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	—

dataset full type

{
  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

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	—

ingestion full type

{
  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

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

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.

datasets full type

{
  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

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	—

schema full type

{
  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

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	—

dataSource full type

{
  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

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

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	—

dataSource full type

{
  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

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.

dataSources full type

{
  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

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.

dateRange full type

{
  from: string,
  to: string,
  granularity: daily | weekly | monthly | quarterly | yearly | allTime
}

filters full type

{
  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	—

metric full type

{
  id?: string | null,
  name?: string | null,
  sourceId?: number | null
} | null

dataPoints full type

{
  date?: string | null,
  value: number | null,
  dimensions?: Record<string, any> | null
}[]

syncInfo full type

{
  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

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.

metrics full type

{
  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
}[]

Overview

Plugins

Databox API reference

Auth

validateKey

Dashboards

list

Datasets

create

get

getIngestion

ingestData

list

listData

Data Sources

create

delete

get

list

Metrics

getData

list

​Auth

​validateKey

​Dashboards

​list

​Datasets

​create

​get

​getIngestion

​ingestData

​list

​listData

​Data Sources

​create

​delete

​get

​list

​Metrics

​getData

​list

Auth

validateKey

Dashboards

list

Datasets

create

get

getIngestion

ingestData

list

listData

Data Sources

create

delete

get

list

Metrics

getData

list