FAQs

Keys & authentication

How do I authenticate to the REST API?

Send your Trace API key in the X-API-Key header on every request. See Authentication for the key classes and which endpoints each one reaches.

How does MCP authenticate?

MCP uses OAuth through your Trace user account — there is no API key field for MCP clients. The client opens a browser sign-in on first connect and stores the token itself. See MCP setup.

Where do I create and rotate keys?

In the Trace app under Settings → API Key. The full key is shown once and can’t be retrieved again, so store it before closing the dialog. Rotating issues a new key and invalidates the old one.

Can I use a key in browser or mobile code?

No. Treat a key like a password: keep it server-side, never commit it, and never ship it in a client bundle where anyone can read it.

Credits & metering

When does Trace charge credits?

Metered REST and MCP operations charge for net-new company records returned, with a re-access window for recently unlocked companies. Credits & usage has the full model.

Does re-reading the same company cost again?

Not within the re-access window — a company you’ve already unlocked is free to read again for 30 days. Only net-new companies draw down credits.

What happens when credits run out?

The API or MCP tool returns a structured insufficient-credit error instead of returning data. Nothing is charged and no partial result is returned.

Do MCP and the REST API share one credit pool?

Yes. Both draw on the same monthly allocation, so usage from an agent and from your own services counts against the same balance.

Coverage & data

How current is the technology data?

Trace re-crawls on a rolling schedule, and every technology carries first_seen and last_seen so you can judge freshness per signal rather than assuming a single site-wide age.

Why does a company return fewer fields than the examples?

Fields with no data are omitted rather than returned as null, so a real response is often smaller than a documented example. Treat every field as optional.

What if a company's data looks wrong?

Send it back to us through the data flags API and it goes into the review queue. Flagging a specific field is more actionable than flagging the company.

Can I look a company up by something other than its domain?

Yes — company endpoints accept either a domain or a Trace slug as the identifier. See the Companies API.

Errors & limits

What error format does the REST API use?

Structured JSON errors with a code or validation detail and a message that explains the failure. Errors lists the status codes and shapes.

How should clients handle rate limits?

Back off and retry after the indicated delay when a 429 is returned. Rate-limit headers on every response tell you how much budget is left before you hit one.

Is there a sandbox for trying requests?

The interactive reference runs real requests in the browser. Without a key it shows sample responses; with one it hits your own data and meters normally.