View API usage

GET /v1/usage

https://api.voygr.tech/v1/usage

Open in playground

Overview

Get current usage, quota, and reset date for the API key.

Authentication

API key in header X-API-Key: Your customer API key (pk_live_...), sent on every request. Self-serve at https://api.voygr.tech/checkout.

Responses

`200`

Successful Response

application/json

Schema: UsageResponse

`401`

Missing API key header

application/json

Schema: ErrorResponse

Example

{
  "success": false,
  "error": "API key required. Include X-API-Key header.",
  "error_code": "AUTHENTICATION_ERROR",
  "request_id": "ad33009a-fdfe-4e25-9650-4a49099c3d4a"
}

`403`

Invalid, revoked, or unauthorized API key

application/json

Schema: ErrorResponse

Example

{
  "success": false,
  "error": "Invalid or revoked API key",
  "error_code": "AUTHENTICATION_ERROR",
  "request_id": "25b104f0-9ad0-4fc7-8530-c5d5ff8d9698"
}

`422`

Validation Error

application/json

Schema: HTTPValidationError

Schemas

UsageResponse

Type: object

Response model for usage endpoint.

Field	Type	Required	Description and constraints
`tier`	`string`	required	Account plan identifier associated with the API key.
`api_key_id`	`string`	required	API key ID
`customer_id`	`string`	required	The account this key belongs to. Stable across key rotation; key per-customer client state on this, not on api_key_id.
`key_hint`	`string \| null`	optional	Last 4 characters of the key's plaintext, so the holder can recognise it. null on keys minted before this was recorded.
`key_created_at`	`string \| null`	optional	When this key was minted (ISO 8601). null if unknown.
`customer_name`	`string`	required	Customer name
`quota_limit`	`integer`	required	Credit allowance for the current period, not a number of requests.
`current_usage`	`integer`	required	Credits charged plus credits reserved by requests still in progress. Unused reservations are released on settlement.
`remaining`	`integer`	required	Credits available to spend, after charges and current holds. Same value as available.
`available`	`integer \| null`	optional	Credits spendable right now - same value as `remaining`, named for the question callers ask. Already net of credits frozen by in-flight reservations.
`call_credit_hold`	`integer \| null`	optional	Credits ONE outbound call freezes at dial time (a refundable hold, not a charge). available // call_credit_hold is the CREDIT-limited bound on calls in flight - entitlement and the per-customer concurrency cap gate independently, so it is not a guarantee that many will start.
`max_places`	`integer \| null`	optional	Total places search and import may deliver to this key (self-serve trial cap). Null when the key is uncapped.
`places_used`	`integer \| null`	optional	Places delivered so far, plus those reserved by in-flight requests, against max_places. Null when uncapped.
`contact_email`	`string \| null`	optional	The address a support or sales reply would be sent to - the email on this key. Empty string when the key carries none, in which case POST /v1/contact requires `reply_to`. Null from a backend that predates the field.
`credits_per_field`	`integer \| null`	optional	Credits one (place × field) fill costs in deep research.
`credits_per_place`	`integer \| null`	optional	Credits one found/imported place costs (places search + import).
`open_invoices`	`array of object \| null`	optional	Open (unpaid) invoices raised for this key, newest first.
`percentage_used`	`number`	required	Percentage of quota used
`reset_date`	`string`	required	Date when usage resets (YYYY-MM-DD)
`period`	`string`	required	Quota period (monthly, weekly, daily)
`status`	`string`	required	API key status (active, revoked, suspended)
`validation_timestamp`	`string \| null`	optional	UTC timestamp when usage response was produced (ISO 8601).

Example 1

{
  "api_key_id": "f4d0a2c2-f73f-4de6-ac3e-f42ce35af4d6",
  "customer_id": "cus_0001example",
  "customer_name": "Acme Inc",
  "quota_limit": 10000,
  "current_usage": 2375,
  "remaining": 7625,
  "percentage_used": 23.75,
  "reset_date": "2026-03-31",
  "period": "monthly",
  "status": "active",
  "tier": "<account-plan>"
}

Example 2

{
  "api_key_id": "eaa59659-7fab-4d1f-a80d-4f1e0f9388e4",
  "customer_id": "cus_0002example",
  "customer_name": "Beta Foods",
  "quota_limit": 5000,
  "current_usage": 5000,
  "remaining": 0,
  "percentage_used": 100.0,
  "reset_date": "2026-03-01",
  "period": "monthly",
  "status": "active",
  "tier": "<account-plan>"
}

ErrorResponse

Type: object

Error response model.

Field	Type	Required	Description and constraints
`success`	`boolean`	optional	Always false for errors default False
`error`	`string`	required	Error message
`error_code`	`string \| null`	optional	Error category code (VALIDATION_ERROR, MODEL_ERROR, EXTERNAL_API_ERROR, etc.)
`request_id`	`string \| null`	optional	Request ID for tracing
`validation_timestamp`	`string \| null`	optional	UTC timestamp when error response was produced (ISO 8601).
`detail`	`object \| null`	optional	Additional error details

Example 1

{
  "success": false,
  "error": "API key required. Include X-API-Key header.",
  "error_code": "AUTHENTICATION_ERROR",
  "request_id": "ad33009a-fdfe-4e25-9650-4a49099c3d4a"
}

Example 2

{
  "success": false,
  "error": "Invalid or revoked API key",
  "error_code": "AUTHENTICATION_ERROR",
  "request_id": "25b104f0-9ad0-4fc7-8530-c5d5ff8d9698"
}

HTTPValidationError

Type: object

Field	Type	Required	Description and constraints
`detail`	`array of ValidationError`	optional

ValidationError

Type: object

Field	Type	Required
`loc`	`array of (string \| integer)`	required
`msg`	`string`	required
`type`	`string`	required
`input`	`any`	optional
`ctx`	`object`	optional