Request & Response Envelope

Every response uses a consistent JSON envelope. Learn it once and you can read any endpoint.

The envelope

{
  "status": "success",
  "code": 200,
  "message": "Human-readable summary.",
  "data": [ ... ]
}

Field	Type	Meaning
`status`	string	`"success"` or `"error"`.
`code`	integer	Mirrors the HTTP status code of the response.
`message`	string	Human-readable summary. Safe to log; not for branching logic.
`data`	array / object	The payload. Reads return the resource(s); some responses return `[]`.

Branch your code on status and the HTTP status code - not on message. Messages are wording that can change; status and code are stable.

Success - single resource read

{
  "status": "success",
  "code": 200,
  "message": "...",
  "data": [
    { "id": 123, "name": "..." }
  ]
}

Paginated responses

Reads come in two shapes under data:

Flat reads return a bare array directly under data - the single-resource reads and most reference catalogs.
List and large-catalog reads wrap the array in a pagination object: data carries an items array plus a pagination block with current_page, per_page, total and last_page.

{
  "status": "success",
  "code": 200,
  "message": "...",
  "data": {
    "items": [ { "id": 88, "name": "..." } ],
    "pagination": { "current_page": 1, "per_page": 25, "total": 137, "last_page": 6 }
  }
}

Paginated reads accept page, per_page and search query parameters. The per_page default and cap depend on the surface:

Surface	Default `per_page`	Cap
Resource lists (audiences, activations, cohorts, projects, schedules)	25	100
Reference reads (Common, Web, CTV)	500	500
Apps reference reads	250	uncapped

Each endpoint’s page documents its exact paging. See Limits & Quotas for the full table.

Error envelope

Errors keep the same top-level shape with status: "error" and an errors object describing what went wrong:

{
  "status": "error",
  "code": 422,
  "message": "Validation error.",
  "data": [],
  "errors": {
    "field_name": [
      "The field_name field is required.",
      "The field_name field is required to be string type."
    ]
  }
}

See Errors for each status code.

Datasets Status Codes