Bring your own keys. Share a free one with the pool if you want. [ GET YOUR VAULT ]

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/v1

All 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, default false) — 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, default false) — also return coming_soon and disabled models, 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

authentication_error

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 from GET /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 declared inputs. Extra top-level fields are folded into params, so {"model": …, "seed": 7} and {"model": …, "params": {"seed": 7}} are equivalent; an explicit params entry wins on a clash.

  • prompt (string, optional) — a saved-prompt reference, either prompt:<public_id> or prompt.<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 a prompt.<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

missing_text

a text-to-speech call arrived with no text input

pass the model's declared text field

404

model_not_found

no media model has that descriptor id

list valid ids with GET /media/models

422

invalid_param

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

adapter_not_available

the model is active but its provider has no generation adapter

pick another model of the same modality

502

generation_failed

the provider failed to generate

retry once, then try another model

502

empty_result

the provider returned no image or audio bytes

retry once, then try another model

502

decode_failed

the provider returned an undecodable image

retry once, then try another model

503

model_not_available

the model is coming_soon or disabled

pick an active model from GET /media/models

503

no_<provider>_key

your brand holds no key for that provider, e.g. no_kie_ai_key

register one at The Key Vault

503

malformed_credential

the stored credential for that provider has no api_key

re-enter the key in the vault

429

<provider>_quota_exhausted

the key's plan has used its allowance for this model in the current window, e.g. minimax_quota_exhausted

wait for the reset: the response carries a Retry-After header and error.retry_after (seconds) when the provider gives one; no header means the reset is unknown

429

<provider>_rate_limited

the provider rate-limited the request

retry shortly

504

generation_timeout

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         13

Two 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. Read not_entitled_reason to 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 provider 404/429 as 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 as model to POST /media/generations, e.g. minimax/image-01.

  • served_on_key: true when the plan carries an allowance for the model. It stays true while the current window is used up; detail then says when it resets, and a generation answers 429 with Retry-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_key and the key's usage policy lets a media generation through for your consumer. The reason is one of not_served_on_key, activity_not_allowed (the key's allowed activities lack media) or consumer_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

task_id

string, 1–128 chars

yes

The task id the token was minted with.

since

ISO 8601 datetime

no

Inclusive lower bound. A time without a zone is read as UTC.

until

ISO 8601 datetime

no

Exclusive upper bound. Must be later than since.

format

json · yaml · md · llm

no

Response rendering. md returns a table; yaml the same fields as JSON; llm is the JSON body. Default json.

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 header

The 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_by says whose key served: own (your company's), group:<group name> (a connected company's), pool (the shared pool) or unknown (no key was recorded on the row).

  • integration_id is set for your own and your connected companies' keys, and null for a pool key. label is set only for your own keys.

  • attempts counts rows, one per attempt, so a retried turn counts each try. counted_as says so.

  • At most 50 groups come back; truncated: true means more matched. lease_ids holds at most 50 ids per group.

  • Requests made before 2026-10-21 carry a task_id on chat requests only. Since then lease, embedding, media and judge requests carry it too.

Errors

Status

Code

When

What to do

401

missing_api_key / invalid_api_key

No Authorization header, or the credential is wrong or revoked.

Send Bearer client_id:api_key:api_secret or a spideriq_pat_… token.

422

invalid_time_range

since is not earlier than until.

Swap or widen the bounds.

422

SCHEMA_VALIDATION_FAILED

task_id is missing, empty or longer than 128 characters, or a date does not parse.

Send the task id as given to the token; use ISO 8601 dates.

503

db_unavailable

The gateway is still starting up.

Retry after a short backoff.

500

internal_error

An unexpected failure.

Quote the x-trace-id response header when reporting it.

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

days

integer, 1–90

no

The window for the request counts in my_keys. Default 7.

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 token

The 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_use is the order the gateway tries keys for your requests: your own keys, then your connected companies' keys, then the shared pool.

  • group is null when your company is connected to no other company. That is an answer, not an error.

  • my_keys lists only keys your company owns that carried requests in the window. outside_group_requests counts requests from outside your group (for a key that also serves the pool); it never names who sent them. unattributed_requests are requests logged before the key's owner was recorded.

Errors

Status

Code

When

What to do

401

missing_api_key / invalid_api_key

No Authorization header, or the credential is wrong or revoked.

Send a valid client credential or spideriq_pat_… token.

403

brand_unbound

The credential is not bound to a brand.

Use a credential issued for your brand.

422

SCHEMA_VALIDATION_FAILED

days is below 1 or above 90 (days=0 is refused).

Send a window from 1 to 90 days.

500

internal_error

An unexpected failure.

Quote the x-trace-id response header when reporting it.

Endpoint summary

Authenticated:

  • POST /chat/completions — chat completion, streaming and non-streaming

  • POST /media/generations — schema-aware image, video and speech generation

  • GET /media/models — media models and the parameter schema each one declares

  • POST /images/generations — image generation, OpenAI passthrough

  • POST /audio/speech — text-to-speech, returns audio bytes

  • POST /audio/transcriptions — transcription, multipart upload

  • POST /embeddings — vector embeddings

  • GET /subscriptions — your brand's own subscriptions, the models it may pin, and free lease slots

  • GET /usage/by-task — which keys served one task, grouped by key and request kind

  • GET /group — your connected-companies group, the order keys are used in, and who used your keys

Public, no token:

  • GET /models — list models

  • GET /models/{model_id} — get one model

  • GET /aliases — list task aliases and the slots behind each

  • GET /providers — list providers

  • GET /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-d9edcff2123d

POST /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 example router.

  • 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

  1. Authenticate your calls — Authentication.

  2. Handle failures correctly — Errors.

  3. Stay within limits — Rate Limits & Budgets.