Best practices for agents

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#

Parameters are strict: an unknown or repeated query parameter is 400 invalid_request. Take names, types and ranges from the reference or the OpenAPI file. A 400 is a bug in the request; fix it, do not retry it unchanged. See Response format.

Read the state, not just the rows#

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).

Show 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).

Do not over-claim#

• 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).
• For revisions use as_of to see what was known at a time; do not mix versions silently (Macro).
• Statute text is the current version; verify against the official source for anything that matters.

Handle 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).

Be economical#

• 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#

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).