Docs

FAQ

Empty searches, setup_needed, the 409 on research and evals, the hint after a first connect, and which calls count toward the monthly quota

Short answers to the questions that come up first. Each links to the page with the full contract.

Why is my search empty?

One of three things, and the response says which:

  • Nothing is connected. The result carries setup_needed. Show the user its message and connect_url. See What does setup_needed mean?
  • A source is connected but nothing has synced yet, or nothing matched. There is no setup_needed. Read corpus.empty_reason: no_match means the corpus holds nothing for this query, weak_matches_only means rows came back and none cleared the bar, so rephrase. See The corpus block.
  • The read failed. On the plain-language lane, detail.internal.status: "failed" means the search did not run to the end, for example because the warehouse-read budget ran out. It is not an empty corpus. Retry later.

To see what the workspace holds before you query, call GET /search/overview. row_count: 0 on a surface means nothing has synced to it yet.

What does setup_needed mean?

The workspace has no connected source, so there is nothing for the call to read. reason is always no_sources_connected. message says so in plain words and connect_url is the workspace's Connections page in the console.

On search, and on a research job or eval that still starts, it rides on a normal 200 success. It is not an error. Do this:

  1. Show the user message and connect_url.
  2. Do not retry until a source is connected. The answer will not change.
  3. Do not answer the question from your own knowledge as if it came from the user's data.

Both forms, with example bodies, are in Errors.

Why did research or evals return 409?

The workspace has no connected source and holds no conversation themes, so the job could only come back empty. research.start, and an evals.run whose every case grades against customer conversations, are refused with 409 and error.code: "setup_needed" instead, before a quota call is counted. No job starts.

The body carries the same setup_needed field as the hint, so handle it the same way: show message and connect_url, and do not retry until a source is connected.

An eval still runs with include_external: true, with evidence_from_run or candidate_from_run, or when the eval has a case of only rule or structure graders. See A workspace with nothing connected.

I just connected a source. Why do I still see the hint?

Two steps happen after a connect, and they finish at different times:

  1. The hint clears. Once the connection is live, the next call no longer carries setup_needed. A connect that was started and never finished (an OAuth flow abandoned halfway) does not count, so finish it in the console. GET /connections lists the connection when it is live.
  2. The data appears after the first sync lands. Until then a search is empty without the hint, and an eval comes back not_applicable (empty_corpus). Watch GET /connections/:id/status (is_syncing) or /runs, or check row_count on GET /search/overview, before you run research or an eval.

If the hint is still there after the connect finished, the connection did not complete. Check its health on GET /connections.

Do failed or refused calls count toward my quota?

Only calls made with an API key or an external OAuth token, MCP included, count. Calls from the Amdahl console never count. Of those:

Not counted:

  • A refusal before the work starts: invalid_input and invalid_argument (validation runs before the quota check), forbidden and not_on_public_api, the quota_exceeded refusal itself, and the 409 setup_needed on research and evals.
  • A search whose read fails, and an optimize that returns no rewrite (rate_limited, optimizer_error, optimizer_timeout). On messages.optimize_batch, only items that come back with a result count, as for a single call.

Counted:

  • A search that completes, including an empty result that carries the setup_needed hint, and a plain-language search that returns 200 with detail.internal.status: "failed".
  • An eval run once it is queued, whatever its verdict, not_applicable included.
  • A research job the moment the start is accepted, before it runs, so a start that later fails still counts.

The caps themselves are in Rate limits and Research: Monthly cap. GET /setup/status shows how much of the optimize cap is left.

See also

  • Errors: every error shape and code, and what to do about each
  • Connections: connecting a source and watching its first sync
  • Rate limits: the per-minute limits and the monthly caps