Skip to main content

Consuming via API

Published data products can be read from code through the Nexus gateway, a REST API under /api/v1/gateway on your Qry's own address. It serves BI tools, scripts, internal services and partners that need curated data without direct access to a datasource. To read from Claude or another assistant instead, see Connect an assistant.

Goal​

You finish this page with a credential, a successful read of a published data product, and a clear idea of paging, rate limits and auditing.

Prerequisites​

Steps​

1. Choose the credential​

Who readsCredentialActs as
an applicationan API client's key (qry_…)the API client, with the client's grants
you, from a scripta Nexus access token (qry_nx_…), created in Connect an assistant, or a CLI tokenyou, with your grants and your groups'

A Nexus access token is the narrowest choice for a person: it reads data products and nothing else in Qry. Messaging tokens (qry_msg_…) are refused.

To create an API client, open Nexus, expand API Gateway, choose API Clients and click New client. Give it a Client name, a Description, a Rate limit (req/min), an optional expiry and, optionally, an IP allowlist (CIDR). The key is shown once: copy it then. Qry stores only a hash of it. Rotate key issues a new one; Revoke disables the client.

Then grant the client access on each product it should read.

2. List what you can read​

Every call sends the credential as a bearer token:

curl -sS -H "Authorization: Bearer $QRY_KEY" \
"https://qry.your-company.com/api/v1/gateway/products"

GET /api/v1/gateway/products/{product}/schema returns a product's datasets and columns.

3. Query a dataset​

curl -sS -X POST \
-H "Authorization: Bearer $QRY_KEY" \
-H "Content-Type: application/json" \
-d '{"dataset_name": "active_customers", "filters": {"country": "ES"}, "limit": 1000, "offset": 0}' \
"https://qry.your-company.com/api/v1/gateway/products/customer-360/query"
FieldMeaning
dataset_namethe dataset to read; without it, the first dataset you may read, by name
filterscolumn = value conditions, combined with AND
limitrows per request, 1,000 by default, 50,000 at most
offsetrows to skip, for the next page
formatjson (default), csv or parquet

A JSON response carries columns, rows, total_rows, truncated (the page was full, so there may be more), order_by and stable_order. CSV and Parquet carry the same information in the X-Total-Rows and X-Stable-Order headers.

Your grant's row filter and masked columns always apply, and your own filters are applied on top of them.

4. Page through a large dataset​

Read the next page by raising offset by limit while truncated is true.

Paging is reliable only when stable_order is true: the dataset has a row key, and every page is sorted by it, so none repeats or skips a row. When it is false, the dataset has no row key and its rows may come back in a different order on each request. Read it in one request (up to 50,000 rows), or ask the product's owner to set a row key.

5. Handle limits and quality​

  • Rate limits. An API client has its own limit in requests per minute; a person reading as themselves has 120 per minute. Over the limit the gateway answers 429 Too Many Requests with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). A grant can also cap one product; going over that cap is also answered with 429 (Rate limit for this product exceeded).
  • Quality. If a dataset's quality rules fail, the response says so in X-Quality-Warnings and X-Quality-Mode. When its owner set enforcement to Fail, the gateway serves nothing (422) until the data is fixed.
  • Freshness. GET …/products/{product}/freshness and …/quality report a product's freshness and quality state.

Auditing​

Every call writes a row to the product's Activity: when, the caller, the method and dataset, the status, the latency and the rows returned. The API Gateway view adds usage and activity across all clients.

Common issues​

401 Unauthorized. The key or token is wrong, expired or revoked, or the header is not Authorization: Bearer <credential>.

403 Forbidden. The caller holds no live grant on that product (none, or expired), the product is not published or does not exist (the gateway does not tell these apart, so product names cannot be guessed), or the call came from an address outside the client's IP allowlist.

403 Access denied when asking for a dataset. The grant does not include that dataset. Its owner can add it to the grant's allowed datasets.

Rows or values are missing compared with the source. The grant's row filter or column masks are hiding them. That is by design.

Pages repeat or skip rows. stable_order is false: the dataset has no row key. See step 4.

See also​