# Best practices for agents

> How to use the Aggre API reliably and honestly from an AI agent or automated pipeline.

Page: https://docs.aggre.org/agents/best-practices · Section: For agents · All pages: https://docs.aggre.org/llms.txt

Rules that keep an agent correct, cheap and within the data's terms. Each links to the page that explains it.

## Build requests from the reference, not from memory {#requests}

Parameters are **strict**: an unknown or repeated query parameter is `400 invalid_request`. Take names, types and ranges from the [reference](https://docs.aggre.org/api/data.md) or the [OpenAPI file](https://docs.aggre.org/openapi/data.yaml). A `400` is a bug in the request; fix it, do not retry it unchanged. See [Response format](https://docs.aggre.org/concepts/response-format.md#strict).

## Read the state, not just the rows {#state}

Always read `meta.status` and `meta.message`:

- `empty` is a valid answer. Do not invent rows or conclude "nothing exists" without checking `meta.message` and `meta.fetchedAt`.
- `stale` means the last read is old; say so if you report the data.
- `503 terms_unread` means the source is not switched on. It is not transient and retrying wastes quota ([Freshness](https://docs.aggre.org/concepts/freshness.md)).

## Show attribution {#attribution}

If your output shows a row to a person, include its `credit` / `attribution` exactly as returned, and keep `restricted` notices. Do not paraphrase them ([Attribution](https://docs.aggre.org/concepts/attribution.md)).

## Do not over-claim {#claims}

- Name lists are exact or prefix name search only. **Never present a result, or the absence of one, as a sanctions screening.**
- Congress trades are disclosed weeks late and in ranges; Taiwan statements are in thousand NT$; funding rates are per the venue's own period. Read the field definitions before computing with them ([Datasets](https://docs.aggre.org/datasets.md)).
- For revisions use `as_of` to see what was known at a time; do not mix versions silently ([Macro](https://docs.aggre.org/datasets/macro.md#revisions)).
- Statute text is the current version; verify against the official source for anything that matters.

## Handle errors {#errors}

Log `error.code` and `request_id`. Retry only `429 rate_limited` (after `Retry-After`) and transient `503 store_unavailable` / `500` with backoff. Never retry `usage_limit_exceeded` ([Errors](https://docs.aggre.org/concepts/errors.md#handling)).

## Be economical {#economy}

- Use the largest sensible `limit`, follow `next_cursor`, and cache catalogues.
- Use `updated_since` change feeds instead of re-reading datasets.
- Read `/llms.txt` once and fetch only the `.md` pages you need instead of crawling the HTML.
- Check `GET /v1/whoami` before a large job to see how much quota is left.

## Protect the key {#key}

Keep the key in the tool's secret store. Never echo it, log it, put it in a URL or send it to a model as text. If it leaks, revoke it in the console and create a new one ([API keys](https://docs.aggre.org/console/api-keys.md)).