Make your first call

Authentication

Send your key as a bearer token: Authorization: Bearer $TASKROUTER_API_KEY. The OpenAI SDKs do this automatically from api_key. The base URL is https://api.taskrouter.com/v1.

Keys belong to your organization and draw from its prepaid credit. Create one per environment or app under API keys, and revoke any key on its own. Keep keys server-side: never ship one in browser or client-side code.

Calling any model

Set model to any model ID listed as Ready to run in the model catalog and the request goes straight to that model. Use a task route (taskrouter/<task>) when you want us to pick the model for you from measured results.

Your 24-hour reportComing soon

Detailed 24-hour traffic analysis and automatic task workload detection will provide visibility into calls, tokens, spend, and estimated savings per detected task type. This reporting feature is currently under active development.

How tasks are identified

A task is repeatable work with a clear right answer, such as triaging an email, verifying compliance, or extracting clauses. Routing happens per task, so a task can move to a smaller, faster model without affecting other traffic.

1. Detected in your traffic (Coming soon). Automatic grouping of your traffic calls into tasks.
2. Defined by you. Custom benchmarks and validation datasets to test candidate models against your exact requirements.
3. From the catalog. Common tasks are already benchmarked and available for task route creation today.

How routing works

Rather than guessing from leaderboards, Task Router measures models on standardized benchmarks and routes each request to the model that best fits your policy.

Choose your priority

Set it per request with the x-taskrouter-priority header:

client = OpenAI(
    base_url="https://api.taskrouter.com/v1",
    api_key=os.environ["TASKROUTER_API_KEY"],
    default_headers={"x-taskrouter-priority": "accurate"},
)

What happens to a request

1. The request is routed according to your pinned task route (taskrouter/<task>).
2. Only models that scored at or above your quality floor qualify. A cheaper model never gets your traffic unless it has demonstrated sufficient accuracy.
3. Your policy priority picks the primary model, with the next best models acting as automatic fallbacks.

Model names

Task Routes

A task route binds one task to a stable alias, taskrouter/<task>. You choose the quality floor, an optional latency cap, and a priority (cheapest, balanced, or accurate). Only models that clear your floor on that task’s benchmark are eligible, arranged in fallback order.

With auto-optimize enabled, the route automatically updates when new models are measured or prices change, keeping your alias completely stable.

Task input and output formats

Send the raw input as the user message (e.g. email body, query text, document snippet). The route automatically provides task instructions for whichever model it picks, eliminating prompt boilerplate.

Each task details what to send, sample return schemas, and allowed categorical values. For example, Inbox Triage returns:

{ "label": "Urgent" }   // always "Urgent", "Read Later" or "Spam"

Response headers

Errors

• 401 Missing, invalid, or revoked API key.
• 402 Prepaid credit balance exhausted. Add credit on the Credits page.
• 404 Unknown task route or alias. Check your created task routes.
• 429 Rate limit exceeded. Retry with exponential backoff.

Credits and pricing

• Inference: Billed at provider list price without markup.
• Routing: First 1,000 routing decisions free each month, then $0.15 per 1,000. A routing decision is one API request that Task Router sends to a model for you.
• $5 credit: Included upon registration. Top up prepaid balance anytime on Credits. Signup credit works with the models marked “Included with your access” on the Models page. Other models need added credit.

Streaming

Pass stream=True (Python) or stream: true (TypeScript). Standard Server-Sent Events (SSE) streaming chunks arrive in OpenAI format.