---
title: "Your IC Credits console state, or poll a queued request"
method: GET
path: "/api/credits/status"
tags: ["keys", "browser-session"]
---

# Your IC Credits console state, or poll a queued request

`GET /api/credits/status`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/credits/status`
- Auth: API key in cookie `__session`

Clerk-session only (NOT reachable with an agt_ bearer). WITHOUT `request_id`: the member's console state ({ ok, has_key, token_prefix?, kind?, budget_usd?, budget_used_usd?, budget_remaining_usd?, budget_period?, budget_resets?, by_model?, default_model?, pending_request? }). WITH `request_id`: the pre-IC-Credits poll answer, byte-identical, returning ONLY the status. A request that does not exist and a request owned by somebody else return a BYTE-IDENTICAL 200 `{ ok: false, status: "not_found" }`, so this cannot be used as an existence oracle. Stop polling on approved / denied / not_found.

## Query parameters

- `request_id` string

## Response `200`

The console state, the request's status, or the soft-not-found.

- CreditsStatusResponse: Two shapes on one path. WITHOUT request_id: `{ ok: true, ...CreditsStatus }`. WITH request_id: `ok: true` with pending/approved/denied means the caller owns the request (plus `usage` for an approved member key whose meter could be read); `ok: false` with `status: not_found` is the soft-not-found returned identically for an unknown id AND for one owned by somebody else.
  - `ok` boolean, required
  - `has_key` boolean: Console shape only.
  - `status` 'pending' | 'approved' | 'denied' | 'not_found': Poll shape only.
  - `usage` CreditsUsage: The spend summary for one member key: the same figures ic_credits_usage returns.
    - `budget_usd` number, nullable: The key's monthly budget of IC Credits in USD; null only on a legacy weekly-token key.
    - `budget_used_usd` number: Spent against the budget (month cost, or lifetime total for a lifetime budget).
    - `budget_remaining_usd` number, nullable
    - `budget_period` 'month' | 'lifetime' | 'null', nullable
    - `budget_resets` string, nullable: YYYY-MM-01 of the next month (UTC), or never.
    - `by_model` object[]
      - `model` string
      - `provider` string
      - `tokens` integer
    - `default_model` string: The model the key's bundle pins as ANTHROPIC_MODEL.
    - `weekly_used` integer
    - `weekly_remaining` integer, nullable: null on a usd_budget key.
    - `weekly_cap` integer, nullable: Legacy weekly-token keys only; null otherwise.
    - `multiplier` integer, nullable
    - `reset_date` string: Next Monday (UTC), YYYY-MM-DD.
    - `month_cost_usd` number: Metered cost this month.
    - `month` string: YYYY-MM (UTC).

## Other responses

- `400`: request_id present but empty.
- `401`: Not signed in.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)