Skip to main content
Every response from the Conduit API shares one shape. There is exactly one envelope. Whether you request a list or a single item, you read the payload from data and the bookkeeping from meta. You never have to special-case the parsing logic per endpoint. This page describes the envelope, every meta field, and how the request identifier flows through both successful and error responses for tracing.

​
The two payload shapes

data is the only field whose type varies, and it varies in exactly one way:
  • List responses put an array in data. List responses are the ones that paginate, so their meta carries a pagination block.
  • Item responses put a single object in data. Item responses describe one resource (for example one country, one entity, or one provenance chain) and do not paginate.
Everything else (the meta block, the top-level requestId) is identical across both. 
{
  "data": [
    {
      "indicator": "cpi_inflation_yoy",
      "country": "USA",
      "value": 3.2,
      "period": "2026-05",
      "freshness": "fresh"
    }
  ],
  "meta": {
    "request_id": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
    "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
    "api_version": "v1",
    "pagination": {
      "limit": 100,
      "cursor": null,
      "next_cursor": null,
      "has_more": false
    }
  },
  "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55"
}
Only list responses include meta.pagination. Item responses omit it because there is nothing to page through.

​
Top-level fields

​
data
array | object
required
The response payload. An array for list endpoints, a single object for item endpoints. This is the only field whose type changes between response kinds.
​
meta
object
required
Response metadata: the request identifier, the API version, and (on list responses) the pagination block. See below.
​
requestId
string
required
The request identifier, repeated at the top level for convenience. Identical to meta.request_id and meta.requestId. Quote this value when you contact support.

​
The meta block

​
meta.request_id
string
required
A UUID that uniquely identifies this request on the server. Logged server-side, so it lets support trace exactly what your call did.
​
meta.requestId
string
required
The same UUID as meta.request_id, provided in camelCase as well so clients in either naming convention can read it without transformation.
​
meta.api_version
string
required
The API version that served the response. Always "v1" for the current surface. Every data path lives under /v1, and this field mirrors that.
​
meta.pagination
object
Present on list responses only. Carries the cursor state for paging through results. See the Pagination page for the full loop.

​
The request identifier

Both successful and error responses carry the same identifier in three places: meta.request_id, meta.requestId, and the top-level requestId. They always hold the same value within one response. The redundancy exists so you can read the identifier whether your code expects snake_case or camelCase, and whether it inspects the envelope root or the meta block. Capture it on every response, including errors. It is the fastest way for support to find your request in the logs.
Capturing the request id (TypeScript)
const res = await fetch(
  "https://data.quantoraresearch.com/v1/public/observations?country=USA&indicator=cpi_inflation_yoy",
  { headers: { "x-api-key": process.env.CONDUIT_API_KEY! } },
);
const body = await res.json();
console.log("request id:", body.requestId);

​
Error responses

Errors use a sibling envelope: error replaces data, and the request identifier is preserved so failures stay traceable. See the Errors page for the full shape and the code table.
Error envelope
{
  "error": {
    "code": "bad_request",
    "message": "Unknown query parameter: 'contry'",
    "request_id": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
    "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
    "details": {}
  },
  "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55"
}

Pagination

Follow next_cursor while has_more is true.

Errors

The error envelope and the full code table.