Routing and credits
Understand provider attempts, control a routed call, and check what it cost.
How providers are chosen
Tools such as people_search first identify providers that can accept your inputs and are available on the server. They follow the configured order and your applicable preferences. This is not a promise to pick the cheapest or fastest provider every time.
With fallback enabled, the router can try another provider after an error or no match. Most capabilities stop when one provider returns a result; capabilities that combine profiles may collect results from several providers.
Control a routed call
| Option | Effect |
|---|---|
max_credits | Sets a credit ceiling for one routed call. An attempt is skipped if its quoted cost would take the call over that ceiling. |
vendor | Restricts the call to a provider or endpoint ID. |
waterfall: false | Stops after the first attempted provider, even if it returns no match or an error. |
Saved provider preferences and per-capability ceilings are available in Settings. These routing controls apply to capability tools; direct call_tool calls do not use them. A per-call ceiling is not a budget for a whole conversation with multiple calls.
What is charged
Check the current catalog or endpoint details before calling. Prices and billing rules vary by endpoint; requesting more rows can also affect the quoted price.
- A successful attempt is charged at the endpoint's applicable price.
- An empty result can still be charged when the endpoint bills on a miss, including
per_callandper_resultbilling types. - A provider error does not charge that attempt. Other attempts in the same routed call may already have incurred charges.
Read the result and usage
Routed responses include outcome, the normalized output, and _dinq metadata. _dinq.tried lists provider attempts and their credits; _dinq.credits is the total reported for the call. The returned plan describes the candidate order, not a list of successful results.
Use Activity to review recorded provider attempts and Overview to check your balance. One routed task can produce several activity entries.
Per-call limit reached
budget_exceeded means endpoints were skipped because of this call's max_credits, not that your account balance is empty. Skipped endpoints were not called or charged. If some endpoints were attempted, the search may be incomplete. Inspect attempted and skipped counts and ask before increasing the limit, or choose a lower-cost endpoint; do not repeat the unchanged request.
Usage statistics
Usage summarizes the last 7, 30 or 90 days by capability and provider, with endpoint details under each provider. Each recorded API attempt counts as a call, including failures; one task can make several calls. Recorded credits are not a reconciled payment ledger and may differ from final deductions. Statistics can take up to 30 seconds to refresh. Activity retains the latest individual call records.