List virtual keys

GET/v1/virtual-keys

List virtual keys.

Lists an organization's keys, or one workspace's, a page at a time. The filters combine. Each key is returned as by "Get a virtual key": provider keys are never included, only their hints.

Requires a workspace key (member or admin) for workspace_id when it is given, or an organization admin key; an organization-wide list (no workspace_id) requires an organization admin key. 403 otherwise.

Authorization

AuthorizationBearer va_
A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Query parameters

organizationstringrequired
the organization slug
workspace_idstring<uuid>
only keys in this workspace (UUID); omit for every key in the organization
providerstring
only keys with a credential for this provider, e.g. OPENAI
statusstring
only keys in this status: ACTIVE, DISABLED, EXHAUSTED or EXPIRED
pageinteger<int32>
the page number, starting at 1 (default 1)
page_sizeinteger<int32>
keys per page (default 20, at most 100)

Responses

200application/json

totalinteger<int32>
How many keys match the filters, across every page.
pageinteger<int32>
This page's number, starting at 1.
page_sizeinteger<int32>
The page size used (at most 100).
dataobject[]
The keys on this page.
Child attributes
- slugstring
  The key's stable identifier: vk- followed by 16 hex characters. Used in URLs, logs and routing configs.
- token_hintstring
  The last characters of the API key's secret, to tell keys apart. Absent for a key with legacy_auth.
- legacy_authboolean
  True for a key created before API keys existed: its bare slug still authenticates, until the key is rotated for the first time.
- rotated_atstring<date-time>
  When the API key was last rotated (ISO 8601 date-time). Absent if it never was.
- namestring
  The key's name, unique within the organization.
- notestring
  A free-text note about the key. Absent when none was set.
- statusenum<string>
  The key's status:
  - ACTIVE: requests are served.
  - DISABLED: turned off by an admin; requests are refused (403) until it is enabled.
  - EXHAUSTED: its spend reached credit_limit_usd; requests are refused (403) until the limit is raised or removed, the spend resets (credit_reset_policy) or, for a PLATFORM key, credit is added.
  - EXPIRED: past expires_at; final.
  One of "ACTIVE", "DISABLED", "EXHAUSTED", "EXPIRED"
- disable_reasonstring
  The reason given when the key was disabled. Absent unless the key is DISABLED with a reason.
- credential_modeenum<string>
  Where the provider credentials come from: BYOK (your provider keys, in credentials) or PLATFORM (VectorAxis's provider accounts, paid from your organization's credits).
  One of "BYOK", "PLATFORM"
- credentialsobject[]
  The key's provider credentials, as hints only. Empty for a PLATFORM key.
  Child attributes
  - providerstring
    The provider id, e.g. OPENAI (see "List supported providers").
  - key_hintstring
    The last four characters of the provider key, to tell keys apart.
  - vertex_project_idstring
    For a VERTEX_AI credential: the Google Cloud project id. Absent for other providers.
  - vertex_regionstring
    For a VERTEX_AI credential: the Vertex AI region, or global. Absent for other providers.
- organizationstring
  The slug of the organization the key belongs to.
- workspace_idstring<uuid>
  The workspace the key belongs to (UUID).
- created_atstring<date-time>
  When the key was created (ISO 8601 date-time).
- updated_atstring<date-time>
  When the key's settings or status last changed (ISO 8601 date-time).
- expires_atstring<date-time>
  When the key expires (ISO 8601 date-time). Absent: it never expires.
- last_used_atstring<date-time>
  When the key last served a request (ISO 8601 date-time). Absent if it never has.
- total_requestsinteger<int64>
  How many requests the key has served.
- total_cost_usdnumber<double>
  What the key has spent, in USD, since it was created or since its last credit reset. This is the figure credit_limit_usd and credit_alert_threshold_usd are compared with.
- metadatamap<string, string>
  Your own string key/value pairs. Absent when none are set.
- model_allowliststring[]
  The models the key may call; others are refused (403 MODEL_NOT_ALLOWED). Absent: every model.
- credit_limit_usdnumber<double>
  The most the key may spend, in USD, before it becomes EXHAUSTED. Absent: no limit.
- credit_alert_threshold_usdnumber<double>
  The soft spend alert, in USD: at or above it the key carries the ALERT_THRESHOLD_EXCEEDED warning. Absent: no alert.
- credit_reset_policyenum<string>
  When the key's spend goes back to zero: MONTHLY (the 1st of each month, 00:00 UTC), WEEKLY (each Monday, 00:00 UTC) or NEVER.
  One of "MONTHLY", "WEEKLY", "NEVER"
- credit_next_reset_atstring<date-time>
  When the next credit reset is due (ISO 8601 date-time). Absent when the policy is NEVER.
- rate_limit_rpminteger<int32>
  The most requests per minute (a 60-second window). Absent: no limit.
- rate_limit_tpminteger<int32>
  The most tokens per minute (a 60-second window). Absent: no limit.
- rate_limit_rpdinteger<int32>
  The most requests per UTC calendar day. Absent: no limit.
- initial_credits_usdnumber<double>
  For a PLATFORM key: the credit in USD it was created with. Absent for a BYOK key.
- credit_balance_usdnumber<double>
  For a PLATFORM key: what it may still spend, in USD (credit_limit_usd minus total_cost_usd). Absent for a BYOK key, or when there is no limit.
- provider_whiteliststring[]
  For a PLATFORM key: the only providers it may use, as provider ids. Absent: any provider.
- guardrail_slugsstring[]
  Slugs of the guardrails run on every request made with the key. Absent: none.
- markup_pctnumber<double>
  For a PLATFORM key: its own markup on the provider's price, as a fraction (0.06 is 6%). Absent: the platform default markup applies.
- warningsenum<string>[]
  Advisory warnings, computed when the key is read; they never block requests:
  - ALERT_THRESHOLD_EXCEEDED: total_cost_usd has reached credit_alert_threshold_usd.
  - EXPIRING_SOON: the key expires within the next few days.
  Empty when there is nothing to report.

VectorAxis is built by GK Labs, a member of NVIDIA Inception.