Skip to main content
POST
Create dataset

Authorizations

x-api-key
string
header
required

API key for authentication.

Body

application/json
name
string
required

Name for the dataset.

Minimum string length: 1
Example:

"My Portfolio"

description
string

Optional description.

Example:

"Companies in our investment portfolio"

entity_ids
string<uuid>[]

IDs of existing entities to include in the dataset. All IDs must belong to the authenticated organization. If any ID is invalid or not found, the request fails with 400.

Example:

Response

Full dataset object with metadata and current status.

id
string<uuid>
required

Unique identifier of the dataset.

Example:

"ccabb755-afc2-4047-b84c-78d1f23d49b2"

organization_id
string<uuid>
required

Organization that owns this dataset.

Example:

"e5d9e9b0-e415-4941-8ef0-916c5ee56207"

name
string
required

Dataset name.

Example:

"My Portfolio"

description
string | null

Optional description.

Example:

"Companies in our investment portfolio"

entity_count
integer
default:0

Total number of entities in this dataset.

Example:

4

entity_status_breakdown
object

Count of entities grouped by processing status. Keys are status values (ready, pending, enriching, failed); values are entity counts.

Example:
health_score
number

Overall health score of the dataset, from 0 to 100. Reflects how many entities have sufficient identifying information for reliable matching.

Example:

100

health_breakdown
object

Health scores broken down by entity type. Keys are entity types (e.g. company); values are scores from 0 to 100.

Example:
latest_status
enum<string>

Processing status of a dataset.

  • pending: Dataset created, entities queued for enrichment.
  • enriching: Entities are being enriched.
  • ready: All entities enriched and indexed — ready for use in jobs.
  • failed: One or more entity enrichments failed.
Available options:
pending,
enriching,
ready,
failed
created_by_user_id
string<uuid>

ID of the user who created this dataset.

Example:

"870e258e-12ec-4a47-8656-e7a43b0265b3"

created_at
string<date-time>

ISO 8601 timestamp of when the dataset was created. Returned without timezone offset (server-local time).

Example:

"2026-04-08T15:21:36.026993"

updated_at
string<date-time>

ISO 8601 timestamp of when the dataset was last updated. Returned without timezone offset (server-local time).

Example:

"2026-04-08T15:21:38.401148"