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

Your Subscriptions

Your brand's subscriptions are the LLM plans and credentials it has in the vault — a MiniMax package, a Claude Max seat, a pay-as-you-go OpenAI key. GET /api/gate/v1/subscriptions tells you which of them you can actually use right now, and which concrete model ids you may pin.

This is a different question from "what models exist?". The model catalog lists everything SpiderGate can route to, for everybody — over a thousand rows. This page is about the much shorter list your own brand may complete on today.

Who this is for

You, if something on your side chooses the model — a build runner, an orchestrator, a planner that decides (subscription, model) per job, or a script that needs to size how many jobs it can run in parallel.

If you send model: "spideriq/coding" and let the gateway route for you, you do not need this page. That is the point of a task alias: the routing decision is ours. Read on when you want to make that decision yourself.

What this does

For every subscription your brand holds, it answers four things:

  • What can I pin? The concrete model ids, with the id that actually works as model.

  • May I use it? Whether this brand is permitted to complete on that model with that subscription, right now.

  • How do I reach it? Whether you call us and we call the provider, or you borrow the credential and call the provider yourself.

  • How much room is left? For a borrowed credential, how many lease slots are free. One login can carry several slots.

Before it existed, the only way to find out was to send a real request and read the 400 — and a 400 cannot tell "you're not entitled to this model" apart from "that model doesn't exist".

Before you begin

  • A client credential — Bearer <client_id>:<api_key>:<api_secret>. See Authentication.

  • At least one provider key or subscription in your vault. With an empty vault this call succeeds and returns subscriptions: [], which is a real answer rather than an error.

Your brand comes from the credential. There is no brand_id parameter on this route, so there is nothing to set and nothing to get wrong.

Steps

1. Ask what your brand holds

curl -H "Authorization: Bearer $CLIENT_ID:$API_KEY:$API_SECRET" \
  "https://spideriq.ai/api/gate/v1/subscriptions"

You get one entry per subscription, each with a models list. Full field-by-field detail is in the API reference.

2. Pin the id that belongs to your lane

Each model carries two names, and each one belongs to a different way of reaching it:

::table
Field | Use it for
`call_as` | The **completion** lane. Pass it as `model` on `/chat/completions`. It is the exact string for that row right now, or `null` when this subscription gives you no name to send.
`id` | SpiderGate's name for the row. For most rows it equals `call_as`. For a Codex row it is refused: send `call_as`.
`provider_model_id` | A **leased** credential. When you borrow the credential and run the provider's own CLI, the CLI wants the provider's name — this one.

They are often different. A Codex row has id gpt-6-sol-codex, call_as codex/gpt-6-sol and provider_model_id gpt-6-sol. Pinning SpiderGate's name in the provider's CLI fails: gpt-6-sol-codex in the Codex CLI is a 400. On the completion lane, send call_as. 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.

3. Read two fields before you pin, not one

This is the step that matters most, and the one that is easy to get wrong.

::table
Field | What it promises
`entitled` | **You** may pin it: computed from your own credential with the same rule routing uses. This is the permission answer.
`probe_status` | The model's last scheduled health probe — `ok`, `no_tools`, `error` or `delisted`. It is a **platform-wide** reading taken on one key per provider (a pool key where the provider has one, otherwise one of that provider's brand-owned keys, at most daily) — **not** a reading of your key. `null` means nobody has measured it: not healthy, and not broken either.

A null is often structural rather than pending. Some models sit outside the set the probe visits, and a lease-only provider (Claude Code, Gemini CLI) is never completion-probed at all — so waiting will not turn every null into a verdict. Decide on entitled; use probe_status to rank.

entitled: true with probe_status: null is a permitted but unverified model, and it is the common case, not an edge case. On one real brand on 31 August 2026, of the 25 entitled models the endpoint returned, 2 had a probe status of ok, 8 were error, 2 were delisted, and 13 had never been probed at all.

On the same call, four models reporting entitled: true were refused by their provider — two 404, two 429. The endpoint was not wrong: permission really was ours, and other models on the very same credentials answered normally. Permission and availability are simply two different facts.

So:

  • entitled: false — don't pin it. not_entitled_reason says why.

  • entitled: true, probe_status: "ok" — the strongest signal there is. Prefer these.

  • entitled: true, probe_status: null — permitted and unmeasured. Pin it with a fallback, and expect a provider 404 or 429 sometimes. Do not treat it as unusable.

  • entitled: true, probe_status: "error" or "delisted" — we have watched it fail. Pick something else.

4. Check how the subscription is reached

usage tells you which of two very different things you are holding.

::table
`usage` | What you do | What you get back
`completion` | Call `/chat/completions` with the model id. We reach the provider. | A populated `models` list.
`lease` | Borrow the credential; your own runtime calls the provider. We are never in the completion path. | `lease.free_slots`, `lease.total_slots`, and a `harness` naming the runtime. `models` is deliberately empty.

An empty models list on a leased subscription is correct, not truncated — a borrowed credential is not a menu, because your CLI picks the model.

Some credentials can be reached both ways. lanes lists every lane, primary first — ["completion"], ["lease"], or ["completion", "lease"]. Codex is the dual case: usage is completion and models is populated, and because it can also be leased, harness and lease are present too. lease.unusable_reason answers the lease lane on its own (null = your consumer may lease it), so a completion credential that cannot be leased still reads usable: true.

free_slots is a floor, not a reservation. Leases expire quietly on a timer, so the real number can only go up between your read and your next request. Use it to size a parallel run; don't treat it as capacity someone has set aside for you. Two callers who both read free_slots: 3 can both start three jobs, and one of them will meet a 409.

4b. Read the plan and how much of it is used

Every row carries two more blocks.

plan is the package recorded on the key: tier_key, name, price_month (the list price in price_currency, USD), and window_hours and weekly_cap where the vendor publishes them. It is null when no package is recorded on the key. SpiderGate never guesses a package from the key's label or provider; set it on the key in Gate → Vault.

usage_windows says how much of the plan is used, and where that number comes from:

::table
`source` | Means | Providers
`provider` | SpiderGate read it from the vendor | Codex (re-read every 5 minutes), MiniMax (read weekly, and again whenever the plan answers that it is used up)
`runner` | Your runner reported it after a build | Claude: the same figures as `reported_usage`
`none` | SpiderGate holds no reading for this provider. `windows` is empty, which is not zero use | Grok, Cursor, Qwen, Zhipu and every other provider

windows holds five_hour and seven_day, each {used_percent, resets_at, stale}, and only the windows the reading stated. A ChatGPT Pro seat states its weekly window only, so it has no five_hour; it is left out rather than shown as 0.

Check stale before you use a number. stale: true means the figure belongs to a window that has already ended, so it is not your current usage; note says which window and when it ended. A MiniMax reading is usually a day or more old, so its five_hour is usually stale while its seven_day is not. Reading /subscriptions never calls a provider, so it never refreshes these figures.

A limit answer shows too. When your runner gives a lease back with reason: usage_limited, the window its limit_type names (five_hour or seven_day) shows used_percent: 100 and resets_at until the reset, and note says it came from a limit answer and when. A provider with no reading of its own then shows source: runner. A fresher real reading of that window wins. After the reset the window is left out again: a limit answer is not a reading, so it never turns into 0. A limit that names no 5-hour or 7-day window (a monthly one, say) appears in note only.

5. See the same subscriptions in the dashboard

Everything above is also visible to a human. Sign in and open Gate → Vault at /dashboard/gate/vault. Each subscription appears as a key card showing the provider, whether it is active, its health, and its billing mode — the same rows this endpoint reads. If a subscription came back usable: false, the Vault card is where you reconnect or reactivate it.

6. Or let an agent read it for you

If you work through an AI agent, install the gateway skill and ask in plain language. The skill ships in the @spideriq/gateway-skills package and is installed with the OPVS skills CLI (opvs-skills): the command is under Client aliases. spideriq skills add does not install it. That command installs SpiderPublish project files and exits with an error for any other name.

Then, verbatim:

Check which models our SpiderGate subscriptions entitle us to pin right now, grouped by lane, and mark which of them the platform has already seen answer.

Verify it worked

A healthy response is a 200 whose brand_id matches your own brand and whose subscriptions array has one entry per key in your vault. Cross-check the count against Gate → Vault — they are drawn from the same rows.

To prove the entitlement field is really discriminating rather than saying yes to everything, pick a model with entitled: true and probe_status: "ok" and send it a real completion:

curl -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":"minimax-m2.5-qwen","messages":[{"role":"user","content":"say ok"}]}'

It should return 200. A model id you invent should return 400 — that contrast is the check.

Troubleshooting

::table
What you see | What it means | What to do
`401 missing_api_key` | No `Authorization` header, or it is malformed. | Send `Bearer <client_id>:<api_key>:<api_secret>` — three parts, colon-separated.
`403 brand_unbound` | The credential is valid but is not tied 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. | Retry after a short backoff. Nothing about the request needs to change.
`subscriptions: []` on a `200` | Your brand has no LLM credentials vaulted. | Add one on **Gate → Vault**. This is not an error.
An empty `models` list | Either the subscription is `usage: lease` (correct — your CLI chooses), or no catalog model for that provider is marked configured. | Check `usage` first. If it is `completion`, retry with `?include_unconfigured=true` to see the unconfigured rows.
`usable: false` with `unusable_reason` | The subscription cannot serve anything right now. | Read the reason: `key_inactive` means it was deactivated, often automatically after repeated failures — reconnect it on the Vault page. `consumer_not_permitted` means your consumer is neither on the key's allowlist nor a platform-default consumer (`opvs_runner:*`). `activity_not_permitted` means the key does not allow `interactive_cli`.
A model is `entitled` but the provider still refuses | Permission and availability are different facts. | Check `probe_status`. `null` means nobody has measured it — not that it is broken. Prefer one with `probe_status: "ok"`, or keep a fallback.
`400` from a provider's own CLI on an id this endpoint returned | You pinned `id` or `call_as`, which are SpiderGate's names for the completion lane. | A leased CLI wants `provider_model_id` — for Codex, `gpt-6-sol`, not `gpt-6-sol-codex`.

A freshly connected subscription that you intend to lease is worth a second look. Every key admits the platform default consumer (opvs_runner:*), so a brand-new credential is leasable by your brand's runner tokens as soon as it allows the interactive_cli activity. A consumer of any other shape must be added to the key's allowlist first. Pass your own ?consumer=<your runner id> and the answer will be about your case rather than a generic one.

Related