Skip to main content
POST
Fetch segment data

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

Request body schema.

modelUuid
string<uuid>
required

Model identifier.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
filter
Filter · object
required

Segment filter criteria.

sort
Sort · object[]

Sort criteria for the segment.

limit
number

Maximum number of records to include.

fetchingLimit
number

Number of records to fetch per batch.

fetchingOffset
number

Offset for fetching records.

enrich
boolean

Whether to enrich records with segment membership (adds a _segments column).

sync
boolean

Whether to sync before fetching.

Response

Fetch segment data

records
Records · object[]
required

Fetched segment records.

columns
Columns · object[]
required

Segment columns.

count
number
required

Total number of records.

isRefreshing
boolean
required

Whether a model refresh was still running, so very recent writes may be missing. Fetch again shortly for fresher data.