API Reference
This is the complete list of SpiderGate endpoints. Everything the dashboard, the SDKs, and your agents do goes through these. They're OpenAI-compatible, so an OpenAI client pointed at the base URL works against them directly.
Base URL
https://spideriq.ai/api/gate/v1All paths below are relative to that base. For the OpenAI SDK, set base_url="https://spideriq.ai/api/gate/v1".
Authentication
Endpoints that read or write your data require a bearer token. The model-listing endpoints and /catalog/leaderboard are public; the rest of the catalog surface needs a token. See Authentication for the two token formats and Model Catalog for that surface.
Authorization: Bearer <client_id>:<api_key>:<api_secret>
Authorization: Bearer spideriq_pat_…Chat & generation
These require authentication.
POST /chat/completions
Create a chat completion (streaming or non-streaming). The body is the OpenAI chat-completion request; model may be a task alias or a model id.
Query:
include_route_trace(boolean, defaultfalse) — inline a per-attempt route trace in the response (non-streaming).Response headers:
X-SpiderGate-Fallback-From— present, on streaming and non-streaming answers, when the served model is not the alias's slot-0 model. An alias is a pool, so this does not mean that anything failed.Full parameters: Chat Completions. Streaming: Streaming.
POST /images/generations
Generate images with dall-e-3, dall-e-2, or gpt-image-1. Requires an OpenAI key in the vault. See Images, Audio & Embeddings.
POST /audio/speech
Text-to-speech with tts-1, tts-1-hd, or gpt-4o-mini-tts. Returns audio bytes. Voices: alloy, echo, fable, onyx, nova, shimmer. Formats: mp3, opus, aac, flac, wav, pcm.
POST /audio/transcriptions
Speech-to-text with whisper-1, gpt-4o-transcribe, or gpt-4o-mini-transcribe. multipart/form-data; file cap 25 MB (OpenAI's limit for these models as we know it; not re-read for this page).
POST /embeddings
Vector embeddings with text-embedding-3-large, text-embedding-3-small, or text-embedding-ada-002. dimensions up to 3072 (the width of text-embedding-3-large as we know it; not re-read for this page). Also accepts the SpiderGate aliases agent/embed-small, agent/embed-large and agent/embed, which resolve server side to the matching model. See Images, Audio & Embeddings.
Media (schema-aware)
The two endpoints below are not the OpenAI passthrough above. They route through SpiderGate's adapter-backed pipeline, honour each model's declared parameter schema, and return a stored URL rather than raw bytes. Every media model is paid tier and never pooled, so your brand must hold its own provider key.
GET /media/models
List the media models an agent can call, each with the inputs schema it declares. Read a model's inputs before calling POST /media/generations — parameters the model does not declare are dropped before the provider call.
Parameters
modality(string, optional) — filter to one modality, e.g.text-to-image,text-to-video,image-to-video,tts,lipsync.include_inactive(boolean, optional, defaultfalse) — also returncoming_soonanddisabledmodels, which are not generatable.
Example
curl "https://spideriq.ai/api/gate/v1/media/models?modality=text-to-video" \
-H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET"Response
{
"models": [
{
"id": "kie/veo-3-fast",
"provider": "kie_ai",
"modality": "text-to-video",
"modality_group": "video",
"status": "active",
"inputs": {
"prompt": { "type": "string", "required": true, "control": "textarea" },
"aspect_ratio": { "type": "enum", "default": "16:9",
"enum": ["16:9", "9:16", "1:1"], "control": "segmented" }
}
}
],
"total": 1
}Errors:
Status | Code | Trigger | Resolution |
|---|---|---|---|
401 |
| the bearer token is missing, malformed, or revoked | check the token format in Authentication |
429 | — | the token's per-minute or per-day limit is exhausted | back off, or raise the limit in Rate Limits & Budgets |
POST /media/generations
Generate an image, video, or speech clip from a <provider>/<model> descriptor id. Returns a stored SpiderMedia URL plus a cost breakdown. Video generation is synchronous and can take minutes.
Parameters
model(string, required, 1–128 chars) — the descriptor id fromGET /media/models, e.g.fal/flux-dev,kie/veo-3-fast,openai/tts-1.params(object, optional) — the per-model tunables, validated against that model's declaredinputs. Extra top-level fields are folded intoparams, so{"model": …, "seed": 7}and{"model": …, "params": {"seed": 7}}are equivalent; an explicitparamsentry wins on a clash.prompt(string, optional) — a saved-prompt reference, eitherprompt:<public_id>orprompt.<slug>. The server expands the stored prompt text, model and settings; anything you pass explicitly overrides it.project_id(string, optional) — required only to resolve aprompt.<slug>reference.
Example
curl -X POST "https://spideriq.ai/api/gate/v1/media/generations" \
-H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"model": "kie/veo-3-fast",
"params": {
"prompt": "a slow pan across an empty server room",
"aspect_ratio": "16:9"
}
}'Response
{
"id": "media-6ff96279d9894632b730aa92",
"model": "kie/veo-3-fast",
"provider": "kie_ai",
"request_kind": "video",
"cost_usd": 0,
"billed_usd": 0,
"est_cost": {
"provider_cost_usd": 0,
"billed_usd": 0,
"markup_pct": 0,
"key_ownership": "byok",
"basis": "byok_monthly_package",
"currency": "USD"
},
"stored": true,
"data": [ { "url": "https://media.spideriq.ai/client-…/gate-media/….png" } ],
"ignored_params": [],
"warnings": []
}ignored_params names any parameter the model did not declare, so a silently dropped field is still visible to you. billed_usd is 0 when the generation ran on your own paid key.
Errors:
Status | Code | Trigger | Resolution |
|---|---|---|---|
400 |
| a text-to-speech call arrived with no | pass the model's declared text field |
404 |
| no media model has that descriptor id | list valid ids with |
422 |
| a declared parameter carried an illegal value | the message names the field and lists accepted values; raised before a key is selected, so nothing is spent |
501 |
| the model is active but its provider has no generation adapter | pick another model of the same modality |
502 |
| the provider failed to generate | retry once, then try another model |
502 |
| the provider returned no image or audio bytes | retry once, then try another model |
502 |
| the provider returned an undecodable image | retry once, then try another model |
503 |
| the model is | pick an |
503 |
| your brand holds no key for that provider, e.g. | register one at The Key Vault |
503 |
| the stored credential for that provider has no | re-enter the key in the vault |
429 |
| the key's plan has used its allowance for this model in the current window, e.g. | wait for the reset: the response carries a |
429 |
| the provider rate-limited the request | retry shortly |
504 |
| the run exceeded the wall-clock cap: 600 s image and speech, 900 s video | retry, or choose a faster model |
Note that a long video generation can outlive an intermediate proxy timeout even though the run completes and is billed. If a call returns a gateway timeout, check GET /media/models usage or your Traces before resending — the asset may already exist.
Catalog (public, no auth)
GET /models
List the model catalog in OpenAI list format, each entry with a spidergate_info block. Query params: provider, free_only, configured_only, search, capability, sort_by, limit (1–2000), offset, include_delisted. See Models.
A model whose provider has confirmed it removed is left out of this list, so limit rows are limit models you can call. Pass include_delisted=true to list them as well; each one then carries spidergate_info.delisting with callable: false and the date the provider removed it. GET /models/{model_id} still returns such a model, with the same label.
GET /models/{model_id}
Return one model, or 404 model_not_found if unknown.
GET /aliases
List every task alias with the slots behind it and its 30-day usage. Public, no auth. This is the authoritative list: the slots move as providers change, so read them here rather than hardcoding them. See Task Aliases.
Parameters: none.
Example
curl "https://spideriq.ai/api/gate/v1/aliases"Response — 200, an OpenAI-style list. data holds one entry per alias; models lists the alias's slots in slot order. Slot order is display order, not priority: the slots are one pool, and requests go to the least busy.
{
"object": "list",
"data": [
{
"id": "spideriq/lead-analysis",
"description": "B2B lead analysis and scoring",
"use_case": "Company vitals, pain points, CHAMP scoring, team extraction",
"models": [
{ "provider": "cerebras", "model": "gpt-oss-120b", "spidergate_id": null },
{ "provider": "groq", "model": "llama-3.3-70b-versatile", "spidergate_id": "llama-3.3-70b-groq" },
{ "provider": "minimax", "model": "MiniMax-M2.5", "spidergate_id": "minimax-m2.5-qwen" }
],
"usage": { "requests_30d": 43863, "tokens_30d": 301092346, "cost_30d": 203.16232776 }
}
]
}Errors:
::table
Status | Code | When and what to do
`503` | `service_unavailable` | The routing engine is still starting up. Retry after a short backoff; no request body change is needed.A spidergate_id of null means the model is served under its provider-native id rather than a SpiderGate catalog id. The array length is the number of slots. models[0] is slot 0: it is not served first, unless it is a Codex slot, which is tried before the pool.
GET /providers
List the upstream providers SpiderGate can route to, with model counts and key status.
GET /health
Process liveness check.
curl "https://spideriq.ai/api/gate/v1/health"
# {"status":"healthy","service":"spidergate","version":"…"}Subscriptions (what YOUR brand can pin)
GET /subscriptions
Every LLM subscription your brand holds, the concrete model ids you may pin, whether each one is usable right now, how the subscription is reached, and — for a leased credential — how many accounts are free.
This is not the catalog. GET /models lists every model SpiderGate knows about, for everybody; this endpoint answers the narrower question a routing planner actually has: *of those, which may this brand complete on, with which of its own subscriptions?* Before it existed, the only way to find out was to send a completion and read the 400 — and a 400 cannot tell a model you are not entitled to from a model that does not exist.
The brand is the credential's. There is no brand_id parameter on this route and no header that sets one; you get your own brand or nothing.
Parameters
::table
Name | Type | Default | What it does
`include_unconfigured` | boolean | `false` | Include catalog rows never marked configured. Off by default because a provider can carry 160+ rows and an unconfigured one has not been set up to serve. On brand 7 today this moves the model count from 25 to 471.
`consumer` | string, 1–128 chars | none | For **lease** subscriptions only, the consumer id you would lease as (e.g. `opvs_runner:env_9f3c…`). Supplying it makes the entitlement answer *your* case instead of a generic one, so you learn about a `consumer_not_permitted` refusal here rather than at lease time.Example
curl -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
"https://spideriq.ai/api/gate/v1/subscriptions"Response — 200. subscriptions holds one entry per credential your brand has vaulted, ordered by provider.
{
"brand_id": 51,
"subscriptions": [
{
"provider": "minimax",
"display_provider": "MiniMax",
"billing_mode": null,
"models_source": "catalog",
"models_measured_at": null,
"integration_id": 650,
"account_ref": null,
"label": null,
"cost_type": "subscription",
"usage": "completion",
"lanes": [
"completion"
],
"harness": null,
"is_active": true,
"health_status": "healthy",
"usable": true,
"unusable_reason": null,
"lease": null,
"models": [
{
"id": "minimax-m3",
"call_as": "minimax-m3",
"delisting": null,
"provider_model_id": "MiniMax-M3",
"display_name": null,
"context_window": null,
"max_output": null,
"supports_tools": null,
"entitled": true,
"not_entitled_reason": null,
"probe_status": null,
"served_on_key": null,
"effort_levels": [
"none",
"high"
],
"reasoning_replay": true
}
],
"media_models": [],
"reported_usage": null,
"plan": {
"tier_key": "minimax_m_build",
"name": "MiniMax M Plan — Build · $132/mo (7.5× Go)",
"price_month": 132.0,
"price_currency": "USD",
"window_hours": 5,
"weekly_cap": null
},
"usage_windows": {
"source": "provider",
"measured_at": "2026-10-20T13:49:00Z",
"windows": {
"five_hour": {
"used_percent": 18.0,
"resets_at": "2026-10-20T14:55:00Z",
"stale": true
},
"seven_day": {
"used_percent": 8.0,
"resets_at": null,
"stale": false
}
},
"note": "five_hour is from a window that ended at 2026-10-20T14:55Z"
}
},
{
"provider": "codex",
"display_provider": "Codex / ChatGPT Pro",
"billing_mode": null,
"models_source": "catalog",
"models_measured_at": null,
"integration_id": 671,
"account_ref": "acct_b5fd213c90bcef58",
"label": null,
"cost_type": "subscription",
"usage": "completion",
"lanes": [
"completion",
"lease"
],
"harness": "openai-codex",
"is_active": true,
"health_status": "healthy",
"usable": true,
"unusable_reason": null,
"lease": {
"total_slots": 1,
"free_slots": 1,
"accounts": 1,
"account_slots": null,
"account_free_slots": null,
"unusable_reason": null
},
"models": [
{
"id": "gpt-6-sol-codex",
"call_as": "codex/gpt-6-sol",
"delisting": null,
"provider_model_id": "gpt-6-sol",
"display_name": null,
"context_window": null,
"max_output": null,
"supports_tools": null,
"entitled": true,
"not_entitled_reason": null,
"probe_status": null,
"served_on_key": null,
"effort_levels": [
"none",
"low",
"medium",
"high",
"xhigh"
],
"reasoning_replay": false
}
],
"media_models": [],
"reported_usage": null,
"plan": {
"tier_key": "codex_pro",
"name": "ChatGPT Pro 200 · $200/mo",
"price_month": 200.0,
"price_currency": "USD",
"window_hours": null,
"weekly_cap": null
},
"usage_windows": {
"source": "provider",
"measured_at": null,
"windows": {
"seven_day": {
"used_percent": 41.0,
"resets_at": "2026-10-24T09:30:00Z",
"stale": false
}
},
"note": null
}
},
{
"provider": "anthropic",
"display_provider": "Anthropic",
"billing_mode": null,
"models_source": null,
"models_measured_at": null,
"integration_id": 666,
"account_ref": "acct_edd712206a7f67d7",
"label": null,
"cost_type": "subscription",
"usage": "lease",
"lanes": [
"lease"
],
"harness": "anthropic-claude-code",
"is_active": true,
"health_status": "healthy",
"usable": true,
"unusable_reason": null,
"lease": {
"total_slots": 1,
"free_slots": 1,
"accounts": 1,
"account_slots": null,
"account_free_slots": null,
"unusable_reason": null
},
"models": [],
"media_models": [],
"reported_usage": null,
"plan": {
"tier_key": "claude_max_20x",
"name": "Claude Max 20× · $200/mo (20× Pro)",
"price_month": 200.0,
"price_currency": "USD",
"window_hours": 5,
"weekly_cap": null
},
"usage_windows": {
"source": "runner",
"measured_at": null,
"windows": {},
"note": "the runner has not reported this seat yet"
}
}
]
}This example is the service's own test fixtures run through the route handler. The ids, names and slot counts are synthetic. The fields are exact.
Errors:
::table
Status | Code | When and what to do
`401` | `missing_api_key` | No `Authorization` header, or a malformed one. Send `Bearer <client_id>:<api_key>:<api_secret>`.
`403` | `brand_unbound` | The credential authenticated but is not bound to a brand, so there is no tenant to answer for. Use a brand-scoped client credential.
`503` | `db_unavailable` | The routing engine is still starting up. Retry after a short backoff; nothing about the request needs to change.
`500` | `internal_error` | An unexpected failure. The detail is deliberately generic; quote the `x-trace-id` response header when reporting it.An empty subscriptions: [] is a 200, not a 404 — it means your brand has vaulted no LLM credentials.
Which id to pin
Each row carries three names, and each belongs to one use. To complete, send call_as as model on /chat/completions: it is the exact string for that row right now, or null. id is SpiderGate's name for the row; for most rows it equals call_as, and for a Codex row it is refused (gpt-6-sol-codex is called as codex/gpt-6-sol). provider_model_id is the provider's name — use it when you lease the credential and run the provider's own CLI, which does not know SpiderGate's names: pinning gpt-6-sol-codex in the Codex CLI is a 400, and it wants gpt-6-sol.
A null call_as on a row means this subscription gives you no name to send for it. It does not mean the model cannot be called. A brand's own Codex seat serves that brand's completions: a codex/<slug> request goes to your own seat while it is healthy and serves the model, and to the shared pool otherwise. A Codex row's call_as is set exactly when its entitled is true: when this credential is a seat your request can go to, for a model SpiderGate still offers. Whether the shared pool can serve a model is the catalog's answer: call_as on GET /api/gate/v1/catalog/models. The value is read from one server process's state on each request, so two reads can differ for a moment.
Completion rows and lease rows
::table
`usage` | What it means | Which fields are populated
`completion` | You call `POST /chat/completions` and SpiderGate reaches the provider for you. | `models[]` is the menu. `harness` and `lease` are `null`.
`lease` | You borrow the credential and **your** runtime calls the provider. SpiderGate is never in the completion path. | `lease.free_slots` / `lease.total_slots` and `harness` are populated. `models[]` is deliberately **empty** — a leased credential is not a menu; your CLI chooses.An empty models[] on a lease row is a correct answer, not a truncated one.
usage is the primary lane; lanes lists every lane the credential can be reached through, primary first: ["completion"], ["lease"], or ["completion", "lease"]. The dual case is a provider that serves the completion lane and has a verified inject recipe — Codex. Its row keeps usage: "completion" and a populated models[], and also carries harness and lease, because the same credential can be leased. usable / unusable_reason describe the primary lane; lease.unusable_reason answers the lease lane on its own (null = the consumer you named may lease it).
harness names the build runtime the credential is injected into, and is present whenever lanes contains lease. It is derived from our inject-recipe registry (only a verified recipe counts), not a stored column: anthropic-claude-code, gemini-cli, and openai-codex on a Codex row.
Entitlement is not availability
This is the one thing to get right before you pin anything.
::table
Field | The claim it makes | What it cannot tell you
`entitled` | **We** permit this brand to complete on this model with this subscription, right now. Computed with the same predicate the resolver uses, so it can never promise something routing would refuse. | Whether the provider will actually answer.
`probe_status` | The last scheduled tools[] probe of this model: `ok`, `no_tools`, `error` or `delisted`. A **platform-wide** reading on one key per provider — a pool key where the provider has one, otherwise one of that provider's brand-owned keys the vault lets automated traffic use, at most daily. | Anything about **your** key. And nothing at all when it is `null`: never measured — neither healthy nor broken.entitled: true, probe_status: null is permitted but unmeasured, and it is the common case rather than an edge case. A null is often structural rather than pending: some models sit outside the set the probe visits, and a lease-only provider is never completion-probed — so gate on entitled, and use probe_status to rank. Measured on brand 7 on 2026-08-31, across the 25 entitled models the endpoint returned:
probe_status: "ok" 2
probe_status: "error" 8
probe_status: "delisted" 2
probe_status: null 13Two of twenty-five had been seen to answer. On the same call, four models reporting entitled: true were refused by their provider on a real completion — two 404, two 429 — and all four carried probe_status: null. The endpoint did not lie; permission was genuinely ours, and on the same credentials qwen3-coder-next and deepseek-chat both served 200.
The rule for a planner:
entitled: false— do not pin it. Readnot_entitled_reasonto know why.entitled: true, probe_status: "ok"— the strongest signal available. Prefer these.entitled: true, probe_status: null— permitted but unmeasured. Pin it with a fallback, and treat a provider404/429as expected rather than exceptional. It is not a refusal.entitled: true, probe_status: "error"or"delisted"— we have seen it fail. Prefer another model.
Media models on a subscription
media_models[] lists the image and video models a key's plan serves, read from the provider's own quota endpoint. No generation is spent to find out. Today only MiniMax Token Plan keys carry a reading; every other row has []. Each entry:
id: the descriptor to send asmodeltoPOST /media/generations, e.g.minimax/image-01.served_on_key:truewhen the plan carries an allowance for the model. It staystruewhile the current window is used up;detailthen says when it resets, and a generation answers429withRetry-After.detail: the quota reading behind it (allowance left and reset time, or why the plan does not include the model).usable/unusable_reason:served_on_keyand the key's usage policy lets a media generation through for your consumer. The reason is one ofnot_served_on_key,activity_not_allowed(the key's allowed activities lackmedia) orconsumer_not_allowed.
Refusal codes
not_entitled_reason on a model (null when entitled is true):
::table
Code | Meaning
`key_missing` | No credential row backed the check.
`key_inactive` | The subscription is deactivated — often auto-deactivated after repeated failures.
`key_not_owned` | The credential belongs to a different brand. Re-checked at read time even though it was proved at write time.
`key_inject_only` | The provider is lease-only by ToS; it is never a completion path, whoever owns the key.
`key_type_forbids_model` | A free-purpose key reaching a model that is not free **at that provider**. `(provider, model)` is the unit — the same model name is free at one provider and metered at another.
`key_dedicated_door` | The provider is reached only through its own door (the TypeSafe judge); it is never a completion path.
`codex_model_not_offered` | A Codex row whose model SpiderGate no longer offers, or whose catalog row is hidden. A `codex/<slug>` request for it is refused.
`codex_seat_not_serving` | A Codex row whose credential is not a seat your request is served on right now: not your own serving seat (unhealthy, blocked by its spend limit, or restricted by its owner's policy) and not a shared one. Another seat may still serve the model; the catalog's `call_as` says whether the shared pool can.unusable_reason on a subscription. On a completion row it is no_configured_models, or the refusal of its first model. On a lease row — and in lease.unusable_reason on any row whose lanes contain lease — it is one of:
::table
Code | Meaning
`key_inactive` | The subscription is deactivated.
`key_not_found` | The credential is neither your brand's nor a connected company's credential shared with you.
`activity_not_permitted` | The key is not authorized for `interactive_cli` activity.
`consumer_not_permitted` | Your `consumer` is not admitted: it is not on the key's own allowlist and it does not match the platform default (`opvs_runner:*`). A key with an empty allowlist still admits the platform default, so a freshly connected credential is leasable by its own brand's `opvs_runner:env_<uuid>` tokens as soon as it allows the `interactive_cli` activity. To make a key non-leasable, remove `interactive_cli` from it.Free slots are a floor, never a reservation
total_slots is the sum of every leasable account's lease_slots (1 to 32 each, default 1): how many leases the provider can grant at once. accounts is the number of leasable logins, so several slots can sit on ONE login and draw on that one account's usage limits. A leasable account is an active credential of the auth type its provider's recipe lends: an OAuth login, or for Cursor the stored API key. free_slots is total_slots minus the leases live now, counted per account and never below zero for any one of them.
It is a floor. Leases expire on a TTL and are released silently, so the true number can only rise between this read and your next request. Use it to size a parallel build; do not treat it as capacity you have been granted. Two callers reading free_slots: 3 at the same moment can both start three builds, and one of them will meet 409 no_free_account.
If Redis is unreachable the read degrades to free_slots: 0 with the real total_slots rather than failing — so a 0 here means "no free slot, or we could not tell".
Keys your connected companies share with you
When your company is connected to other companies (see GET /group), the response gains a top-level connected array: one row per key another company in your group shares with you. A key its owner marked Keep private is not in it.
{
"connected": [
{
"integration_id": 4821,
"owner_brand_id": 3307,
"owner_name": "Northwind Labs",
"provider": "openai",
"key_label": "Northwind ChatGPT seat",
"health_status": "healthy",
"use_only": true,
"plan_name": "ChatGPT Plus",
"price_usd_month": 20.0,
"display_email": "ops@northwind.example"
}
]
}A connected row is use only: it can serve your requests, and every change to it (edit, test, revoke) answers 404. Those ten fields are the whole row; usage windows, spend and who holds a lease are never in it. connected is absent, not empty, when your company is in no group, so the response for a brand with no connections is unchanged.
Usage by task
GET /usage/by-task
Which keys served one task, grouped by key and request kind. A task is the task_id your token was minted with (it is stored on every request the token makes), so this answers "which subscription paid for this build, and how much of it did the build use".
The brand is the credential's. You see only your own brand's requests. A task id no request of yours carries is an empty 200, never a 404, so the answer never says whether another brand used that id.
Parameters
Name | Type | Required | What it does |
|---|---|---|---|
| string, 1–128 chars | yes | The task id the token was minted with. |
| ISO 8601 datetime | no | Inclusive lower bound. A time without a zone is read as UTC. |
| ISO 8601 datetime | no | Exclusive upper bound. Must be later than |
|
| no | Response rendering. |
Example
curl -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
"https://spideriq.ai/api/gate/v1/usage/by-task?task_id=build-2026-10-25-checkout&since=2026-10-25T00:00:00Z"
# → 200 {"task_id": "build-2026-10-25-checkout", "group_count": 1, "counted_as": "attempts"}
# → 401 {"error": {"code": "missing_api_key"}} without the Authorization headerThe same read is the gate_usage_by_task MCP tool and, from a terminal, spideriq gate usage-by-task build-2026-10-25-checkout.
Response — 200
{
"task_id": "build-2026-10-25-checkout",
"since": "2026-10-25T00:00:00Z",
"until": null,
"groups": [
{
"key": {
"integration_id": 4821,
"label": null,
"provider": "openai",
"plan": {"tier_key": "chatgpt_plus", "name": "ChatGPT Plus", "price_month": 20.0, "price_currency": "USD"},
"owned_by": "group:Northwind"
},
"request_kind": "chat",
"attempts": 42,
"success": 41,
"errors": 1,
"prompt_tokens": 318204,
"completion_tokens": 21877,
"first_at": "2026-10-25T08:02:11Z",
"last_at": "2026-10-25T08:47:39Z",
"lease_count": 0,
"lease_ids": []
}
],
"group_count": 1,
"truncated": false,
"counted_as": "attempts"
}owned_bysays whose key served:own(your company's),group:<group name>(a connected company's),pool(the shared pool) orunknown(no key was recorded on the row).integration_idis set for your own and your connected companies' keys, andnullfor a pool key.labelis set only for your own keys.attemptscounts rows, one per attempt, so a retried turn counts each try.counted_assays so.At most 50 groups come back;
truncated: truemeans more matched.lease_idsholds at most 50 ids per group.Requests made before 2026-10-21 carry a
task_idon chat requests only. Since then lease, embedding, media and judge requests carry it too.
Errors
Status | Code | When | What to do |
|---|---|---|---|
|
| No | Send |
|
|
| Swap or widen the bounds. |
|
|
| Send the task id as given to the token; use ISO 8601 dates. |
|
| The gateway is still starting up. | Retry after a short backoff. |
|
| An unexpected failure. | Quote the |
Connected companies
GET /group
Your company's connected-companies group: which companies you are connected to, how many keys each one shares, the order the gateway tries keys in, and how many requests each company sent through the keys your company owns.
This route only reads. Connecting a company, disconnecting one, pairing with a code and turning Keep private off are done by a human admin in the dashboard, under Vault > Settings. The brand is the credential's; there is no brand parameter.
Parameters
Name | Type | Required | What it does |
|---|---|---|---|
| integer, 1–90 | no | The window for the request counts in |
Example
curl -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
"https://spideriq.ai/api/gate/v1/group?days=30"
# → 200 {"group": {"order_of_use": ["own", "connected", "pool"]}, "window": {"days": 30}}
# → 422 error SCHEMA_VALIDATION_FAILED for days=0; 401 missing_api_key without a tokenThe same read is the gate_group MCP tool and spideriq gate group.
Response — 200
{
"group": {
"companies": [
{"brand_id": 3301, "name": "Contoso Studio", "is_mine": true, "keys_shared": 4},
{"brand_id": 3307, "name": "Northwind Labs", "is_mine": false, "keys_shared": 2}
],
"order_of_use": ["own", "connected", "pool"]
},
"my_keys": [
{
"integration_id": 4790,
"provider": "minimax",
"shareable": true,
"keep_private": false,
"total_requests": 1310,
"usage_by_company": [
{"brand_id": 3301, "name": "Contoso Studio", "is_mine": true, "requests": 1102},
{"brand_id": 3307, "name": "Northwind Labs", "is_mine": false, "requests": 196}
],
"outside_group_requests": 12,
"unattributed_requests": 0
}
],
"window": {"days": 30}
}order_of_useis the order the gateway tries keys for your requests: your own keys, then your connected companies' keys, then the shared pool.groupisnullwhen your company is connected to no other company. That is an answer, not an error.my_keyslists only keys your company owns that carried requests in the window.outside_group_requestscounts requests from outside your group (for a key that also serves the pool); it never names who sent them.unattributed_requestsare requests logged before the key's owner was recorded.
Errors
Status | Code | When | What to do |
|---|---|---|---|
|
| No | Send a valid client credential or |
|
| The credential is not bound to a brand. | Use a credential issued for your brand. |
|
|
| Send a window from 1 to 90 days. |
|
| An unexpected failure. | Quote the |
Endpoint summary
Authenticated:
POST /chat/completions— chat completion, streaming and non-streamingPOST /media/generations— schema-aware image, video and speech generationGET /media/models— media models and the parameter schema each one declaresPOST /images/generations— image generation, OpenAI passthroughPOST /audio/speech— text-to-speech, returns audio bytesPOST /audio/transcriptions— transcription, multipart uploadPOST /embeddings— vector embeddingsGET /subscriptions— your brand's own subscriptions, the models it may pin, and free lease slotsGET /usage/by-task— which keys served one task, grouped by key and request kindGET /group— your connected-companies group, the order keys are used in, and who used your keys
Public, no token:
GET /models— list modelsGET /models/{model_id}— get one modelGET /aliases— list task aliases and the slots behind eachGET /providers— list providersGET /health— liveness check
Observability
Every response carries enough to reconcile what your code saw with what the Traces view shows. All of it is on the normal bearer-authenticated surface; none of it needs a second call.
Response headers
x-trace-id— present on every response. The trace identifier for this request. Log it, then paste it into the Traces search box to find this exact request.X-SpiderGate-Fallback-From— present, on streaming and non-streaming answers, when you asked for a task alias and the served model is not the alias's slot-0 model. Its value is the slot-0 model. An alias is a pool, so its presence means a slot other than slot 0 served. It does not mean that anything failed.
The response body's model field is always the model that actually served the request, which is not necessarily the model you sent. Compare the two to detect a silent fallback.
curl -sD - -X POST "https://spideriq.ai/api/gate/v1/chat/completions" \
-H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
-H "Content-Type: application/json" \
-d '{"model":"spideriq/fast","messages":[{"role":"user","content":"hello"}]}' \
-o /dev/null | grep -i 'x-trace-id\|fallback-from'
# x-trace-id: 441c7118-77b3-4e33-a369-d9edcff2123dPOST /chat/completions?include_route_trace=true
Add ?include_route_trace=true to POST /chat/completions to inline the per-attempt dispatch detail in the response body (non-streaming). Use it when you need to know why a request took the path it did.
curl -s -X POST "https://spideriq.ai/api/gate/v1/chat/completions?include_route_trace=true" \
-H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
-H "Content-Type: application/json" \
-d '{"model":"spideriq/fast","messages":[{"role":"user","content":"hello"}]}'The response gains a route_trace array, one entry per dispatch attempt:
{
"id": "chatcmpl-5e780d89033f433ea999879e",
"model": "nvidia_nim/meta/llama-3.1-8b-instruct",
"route_trace": [
{ "attempt": 0, "path": "router", "model": "spideriq/fast", "outcome": "success", "latency_ms": 390 }
]
}Each entry carries:
attempt(integer) — zero-based attempt index. More than one entry means the first choice did not serve.path(string) — which dispatch path handled the attempt, for examplerouter.model(string) — the model or alias tried on this attempt.outcome(string) —success, or the failure classification for that attempt.latency_ms(integer) — wall-clock time for the attempt.
Errors: include_route_trace is a boolean query parameter. A value that is not a boolean (?include_route_trace=maybe) is refused with 422 and code SCHEMA_VALIDATION_FAILED; it is not ignored. true and false never change the status code of a request that would otherwise succeed. Authentication, budget, model-permission and rate-limit failures return their usual 401 / 402 / 403 / 429 before any dispatch happens, so no route_trace is present on those responses. See Errors.
Reading traces back
Stored traces are read with a bearer token: GET /api/v1/brands/{brand_id}/gate/traces lists them (newest first; page from 1, limit 1 to 100, default 50), GET /api/v1/brands/{brand_id}/gate/traces/{trace_id} returns one, and GET /api/v1/brands/{brand_id}/gate/traces/stats/summary the totals. The same routes serve the Traces page. See Usage analytics for the fields.
Dashboard endpoints
The dashboard surfaces (agents, usage, traces, vault) are served by brand-scoped endpoints under /api/v1/brands/{brand_id}/gate/* and accept either your dashboard session or a bearer token (a client credential or a spideriq_pat_…), for a brand the caller belongs to. They power the dashboard and are not part of the OpenAI-compatible surface. The read routes for usage, capacity, flow and traces are documented under Usage analytics.
Two fields on GET /api/v1/brands/{brand_id}/integrations drive the Keep private switch on each of your keys: group_shareable (the key can be shared with your connected companies at all) and serves_public_pool (the key already serves the shared pool, so Keep private cannot hold it back). Connecting companies, pairing and turning Keep private off are dashboard-session acts; a bearer token is refused with 403 human_act_required.
Next steps
Authenticate your calls — Authentication.
Handle failures correctly — Errors.
Stay within limits — Rate Limits & Budgets.