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
- A published data product. See Publishing a data product.
- A grant on it for whoever reads: the application's API client, or you (directly or through a group). See Granting access.
Steps
1. Choose the credential
| Who reads | Credential | Acts as |
|---|---|---|
| an application | an API client's key (qry_…) | the API client, with the client's grants |
| you, from a script | a Nexus access token (qry_nx_…), created in Connect an assistant, or a CLI token | you, 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"
| Field | Meaning |
|---|---|
dataset_name | the dataset to read; without it, the first dataset you may read, by name |
filters | column = value conditions, combined with AND |
limit | rows per request, 1,000 by default, 50,000 at most |
offset | rows to skip, for the next page |
format | json (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 RequestswithX-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(seconds until the window resets). A grant can also cap one product; going over that cap is also answered with429(Rate limit for this product exceeded). - Quality. If a dataset's quality rules fail, the response says so in
X-Quality-WarningsandX-Quality-Mode. When its owner set enforcement to Fail, the gateway serves nothing (422) until the data is fixed. - Freshness.
GET …/products/{product}/freshnessand…/qualityreport 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
- Publishing a data product — datasets, column descriptions and the row key.
- Granting access — what a grant allows.
- Connect an assistant — the same products from Claude.
- Qry Nexus reference — the full feature overview.