---
title: "Get an API key"
method: GET
path: "/api_keys/{id}"
tags: ["API Keys"]
---

# Get an API key

`GET /api_keys/{id}`

## Request

- Base URL: `https://alttext.ai/api/v1`
- URL: `https://alttext.ai/api/v1/api_keys/{id}`
- Auth: API key in header `X-API-Key`

Returns one key, including a revoked one. The token is in the response while the key is active, except to an
assistant connection without write access, which gets only `token_hint` and a `403` for `reveal=true`.
Pass `reveal=true` to record the read in the key's audit trail as a `revealed` event; use it when a person or tool is
deliberately showing the token. A revoked key has no token and records no event.

## Path parameters

- `id` integer, required

## Query parameters

- `reveal` boolean
- `detail` 'full'

## Response `200`

The key. With `detail=full` it also has `usage`.

- union
  - ApiKey: An API key. The API Keys endpoints list and manage `site` keys. Full-access keys, MCP connection keys and the Webflow Designer key are never returned.
    - `id` integer
    - `name` string
    - `kind` 'site': Always `site` here. Full-access keys are created and managed in the dashboard only.
    - `origin` 'unknown' | 'dashboard' | 'api' | 'shopify' | 'bigcommerce' | 'wordpress_connect': Where the key was created.
    - `integration` 'shopify' | 'bigcommerce' | 'wordpress_connect' | 'null', nullable: The integration that created and uses this key, or `null`. Rotating or revoking an integration key stops that integration until it reconnects.
    - `status` 'active' | 'revoked'
    - `token` string, nullable: The key's token, or `null` once the key is revoked or when an assistant connection without write access reads it. Tokens begin with `atai_`. Keys created before that format existed keep their original tokens, which stay valid. Treat the token as a secret.
    - `token_hint` string, nullable: The last four characters of the token, or `null` once the key is revoked.
    - `usage_limit` integer, nullable: The recorded-usage threshold that stops new requests this billing period. In-flight work can still be charged beyond it. `null` means no limit.
    - `credits_used` integer: Credits this key has used this period, counted against `usage_limit`.
    - `billable_credits` integer: Every credit charged to the account through this key this period, whether or not the charge crossed the key's limit.
    - `billable_complete` boolean: Whether every charge in the current period was tracked by the billing-aware release after the operator's verified old-task drain cutoff. False when tracking is incomplete or the cutoff is absent.
    - `period_start` string, date-time, nullable: When the current period started, if the key has been reset.
    - `resets_at` string, date-time, nullable: When the account's current billing period ends, or `null` when it has no active subscription with a renewal date.
    - `previous_period` ApiKeyPreviousPeriod: The credits billed through the key in its last closed period. `null` until the key has had a reset or been revoked.
      - `billable_credits` integer: Every credit charged to the account through this key during that period, whether or not the charge crossed the key's limit.
      - `billable_complete` boolean: `false` when the period started or was recorded before billable credits were tracked, so the number can be low.
      - `recorded_at` string, date-time: When the period closed.
    - `created_by` ApiKeyCreator: Who created the key, from the audit trail. `null` for keys that predate the audit trail.
      - `type` 'user' | 'api_key' | 'mcp_connection' | 'system'
      - `name` string, nullable
    - `created_at` string, date-time
    - `last_used_at` string, date-time, nullable
    - `revoked_at` string, date-time, nullable
  - ApiKeyDetail: An API key. The API Keys endpoints list and manage `site` keys. Full-access keys, MCP connection keys and the Webflow Designer key are never returned.
    - `id` integer
    - `name` string
    - `kind` 'site': Always `site` here. Full-access keys are created and managed in the dashboard only.
    - `origin` 'unknown' | 'dashboard' | 'api' | 'shopify' | 'bigcommerce' | 'wordpress_connect': Where the key was created.
    - `integration` 'shopify' | 'bigcommerce' | 'wordpress_connect' | 'null', nullable: The integration that created and uses this key, or `null`. Rotating or revoking an integration key stops that integration until it reconnects.
    - `status` 'active' | 'revoked'
    - `token` string, nullable: The key's token, or `null` once the key is revoked or when an assistant connection without write access reads it. Tokens begin with `atai_`. Keys created before that format existed keep their original tokens, which stay valid. Treat the token as a secret.
    - `token_hint` string, nullable: The last four characters of the token, or `null` once the key is revoked.
    - `usage_limit` integer, nullable: The recorded-usage threshold that stops new requests this billing period. In-flight work can still be charged beyond it. `null` means no limit.
    - `credits_used` integer: Credits this key has used this period, counted against `usage_limit`.
    - `billable_credits` integer: Every credit charged to the account through this key this period, whether or not the charge crossed the key's limit.
    - `billable_complete` boolean: Whether every charge in the current period was tracked by the billing-aware release after the operator's verified old-task drain cutoff. False when tracking is incomplete or the cutoff is absent.
    - `period_start` string, date-time, nullable: When the current period started, if the key has been reset.
    - `resets_at` string, date-time, nullable: When the account's current billing period ends, or `null` when it has no active subscription with a renewal date.
    - `previous_period` ApiKeyPreviousPeriod: The credits billed through the key in its last closed period. `null` until the key has had a reset or been revoked.
      - `billable_credits` integer: Every credit charged to the account through this key during that period, whether or not the charge crossed the key's limit.
      - `billable_complete` boolean: `false` when the period started or was recorded before billable credits were tracked, so the number can be low.
      - `recorded_at` string, date-time: When the period closed.
    - `created_by` ApiKeyCreator: Who created the key, from the audit trail. `null` for keys that predate the audit trail.
      - `type` 'user' | 'api_key' | 'mcp_connection' | 'system'
      - `name` string, nullable
    - `created_at` string, date-time
    - `last_used_at` string, date-time, nullable
    - `revoked_at` string, date-time, nullable
    - `usage` object: The same usage report the dashboard shows for this key.
      - `health` 'active' | 'at_limit' | 'never_used' | 'stale': `stale` means no use in the last 30 days.
      - `too_large` boolean: `true` when the key's image history was too large to summarize in time, so the image statistics can be missing.
      - `images_last_30_days` integer, nullable
      - `images_last_6_months` object[], nullable
        - `month` string, date
        - `count` integer
      - `images_this_period` integer, nullable
      - `images_window` 'since_reset' | 'last_30_days': What `images_this_period` covers.
      - `domains` object[], nullable: Where this key's images came from, by host.
        - `host` string
        - `count` integer
      - `uploaded_files` integer, nullable: Images uploaded as files rather than fetched from a URL.
      - `credit_history` object[]: Billing periods, newest first. Checkpoint months remain within their billing period. Includes capped usage and uncapped charges; incomplete values are partial totals.
        - `starts_on` string, date, nullable
        - `ends_on` string, date, nullable: `null` for the period still running.
        - `credits` integer
        - `limit` integer, nullable
        - `understated` boolean: `true` when the capped usage meter omitted charged work after reaching its limit.
        - `billable_credits` integer: Uncapped credits charged through this key in this period. A partial total when billable_complete is false.
        - `billable_complete` boolean: Whether all charges in this period were tracked after the verified old-task drain cutoff. Legacy periods remain incomplete.
        - `period_start` string, date-time: Creation or the preceding reset boundary, inclusive.
        - `period_end` string, date-time, nullable: Reset or revocation boundary, exclusive; null while running. Work finishing after revocation is added to the closed revocation period.

## Other responses

- `403`: The request was refused. `error_code` is one of: - `invalid_api_key`: the `X-API-Key` header is missing or doesn't match a key. - `api_key_revoked`: the key was revoked. Create a new key. - `full_access_required`: managing keys needs a full-access key. Create one in the dashboard under Account > API Keys. - `insufficient_scope`: an assistant connection lacks the Manage API keys permission (`required_scope` is `mcp:keys`), or read-only access when changing keys or revealing a token (`mcp:write`). Reconnect with the permission. - `credential_no_longer_authorized`: the account closed or the calling credential lost authority before the mutation acquired its lock. Reconnect or use a current full-access key. - `out_of_scope`: this key can't be used for this request.
- `404`: No manageable key with that ID on this account. `error_code` is `not_found`. Full-access keys, MCP connection keys and the Webflow Designer key are never found here.
- `429`: Too many key requests for this account. The limit is 120 reads and 30 changes per minute, counted per account across all the API Keys endpoints. Wait `Retry-After` seconds. `error_code` is `rate_limited`.

---

[API](https://skmtc.dev/alttext/apis/alttext-ai-api.md) · [All operations](https://skmtc.dev/alttext/apis/alttext-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/alttext/apis/alttext-ai-api/revisions/6eb62e8e450c?raw)