BinderDex API
Usage
Proposed GET /v1/usage
GET/v1/usage
Requires usage:read. No query parameters are accepted; unknown or repeated parameters return 400.
Proposed access: send an X-API-Key header from a server-side integration. Keys are unavailable during preview.
Response shape
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | additionalProperties: false |
data.tenant_id | string | Yes | — |
data.period_start | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
data.period_end | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
data.request_credits_limit | integer | Yes | minimum: 0 |
data.request_credits_used | integer | Yes | minimum: 0 |
data.request_credits_remaining | integer | Yes | minimum: 0 |
data.rate_limit_per_minute | integer | Yes | minimum: 1 |
meta | Meta | Yes | Freshness is evaluated at snapshot_at, which stays original on a batch replay. Other metadata is generated per response. Proposed commercial semantics: successful data calls may consume one request unit, including empty or missing data; replays and errors consume zero. additionalProperties: false |
meta.request_id | string | Yes | pattern: ^req_[a-zA-Z0-9_-]+$ |
meta.snapshot_at | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
meta.billable_units | integer | Yes | [0,1] enum: [0,1] |
meta.idempotent_replay | boolean | Yes | — |
Response headers
| Header | Type | Preview meaning |
|---|---|---|
X-Request-Id | string | Request correlation identifier; safe to send to support. |
X-Request-Credits-Remaining | integer | Organization credits remaining after this request. Present only after successful key authentication. |
X-Request-Credits-Charged | integer | 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. |
Cache-Control | string | private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate. |
Synthetic example
{
"data": {
"tenant_id": "tenant_demo_alpha",
"period_start": "2026-09-01T00:00:00Z",
"period_end": "2026-10-01T00:00:00Z",
"request_credits_limit": 60,
"request_credits_used": 2,
"request_credits_remaining": 58,
"rate_limit_per_minute": 10
},
"meta": {
"request_id": "req_example",
"snapshot_at": "2026-09-06T12:00:00Z",
"billable_units": 0,
"idempotent_replay": false
}
}Nested definitions
These are the exact reusable shapes referenced by this operation. Constraints are derived from the preview contract.
UsageResponseOrganization-wide allowance shared by all keys. UTC subscription period [start,end). Never pass a tenant ID: derive it from the key. This endpoint uses a separate 10/min control bucket and no paid request credits; it remains available at data quota exhaustion.
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | additionalProperties: false |
data.tenant_id | string | Yes | — |
data.period_start | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
data.period_end | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
data.request_credits_limit | integer | Yes | minimum: 0 |
data.request_credits_used | integer | Yes | minimum: 0 |
data.request_credits_remaining | integer | Yes | minimum: 0 |
data.rate_limit_per_minute | integer | Yes | minimum: 1 |
meta | Meta | Yes | Freshness is evaluated at snapshot_at, which stays original on a batch replay. Other metadata is generated per response. Proposed commercial semantics: successful data calls may consume one request unit, including empty or missing data; replays and errors consume zero. additionalProperties: false |
meta.request_id | string | Yes | pattern: ^req_[a-zA-Z0-9_-]+$ |
meta.snapshot_at | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
meta.billable_units | integer | Yes | [0,1] enum: [0,1] |
meta.idempotent_replay | boolean | Yes | — |
Full canonical schema JSON
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string"
},
"period_start": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"
},
"period_end": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"
},
"request_credits_limit": {
"type": "integer",
"minimum": 0
},
"request_credits_used": {
"type": "integer",
"minimum": 0
},
"request_credits_remaining": {
"type": "integer",
"minimum": 0
},
"rate_limit_per_minute": {
"type": "integer",
"minimum": 1
}
},
"required": [
"tenant_id",
"period_start",
"period_end",
"request_credits_limit",
"request_credits_used",
"request_credits_remaining",
"rate_limit_per_minute"
],
"additionalProperties": false
},
"meta": {
"$ref": "#/components/schemas/Meta"
}
},
"required": [
"data",
"meta"
],
"additionalProperties": false,
"description": "Organization-wide allowance shared by all keys. UTC subscription period [start,end). Never pass a tenant ID: derive it from the key. This endpoint uses a separate 10/min control bucket and no paid request credits; it remains available at data quota exhaustion."
}MetaFreshness is evaluated at snapshot_at, which stays original on a batch replay. Other metadata is generated per response. Proposed commercial semantics: successful data calls may consume one request unit, including empty or missing data; replays and errors consume zero.
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | pattern: ^req_[a-zA-Z0-9_-]+$ |
snapshot_at | string | Yes | format: date-time · pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$ |
billable_units | integer | Yes | [0,1] enum: [0,1] |
idempotent_replay | boolean | Yes | — |
Full canonical schema JSON
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"pattern": "^req_[a-zA-Z0-9_-]+$"
},
"snapshot_at": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"
},
"billable_units": {
"type": "integer",
"enum": [
0,
1
]
},
"idempotent_replay": {
"type": "boolean"
}
},
"required": [
"request_id",
"snapshot_at",
"billable_units",
"idempotent_replay"
],
"additionalProperties": false,
"description": "Freshness is evaluated at snapshot_at, which stays original on a batch replay. Other metadata is generated per response. Proposed commercial semantics: successful data calls may consume one request unit, including empty or missing data; replays and errors consume zero."
}ErrorNo secrets, SQL, or stack traces. retry_after_seconds is non-null for 429/503 and matches Retry-After. Retry rate/503 with bounded backoff and jitter; quota retry waits until period_end or explicit upgrade. 401/403/400/409 are not blind-retryable.
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | additionalProperties: false |
error.code | string | Yes | ["invalid_request","invalid_api_key","insufficient_scope","not_found","idempotency_conflict","payload_too_large","unsupported_media_type","rate_limit_exceeded","quota_exceeded","temporarily_unavailable","internal_error"] enum: ["invalid_request","invalid_api_key","insufficient_scope","not_found","idempotency_conflict","payload_too_large","unsupported_media_type","rate_limit_exceeded","quota_exceeded","temporarily_unavailable","internal_error"] |
error.message | string | Yes | — |
error.request_id | string | Yes | pattern: ^req_[a-zA-Z0-9_-]+$ |
error.retry_after_seconds | integer | null | Yes | minimum: 0 |
Full canonical schema JSON
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_api_key",
"insufficient_scope",
"not_found",
"idempotency_conflict",
"payload_too_large",
"unsupported_media_type",
"rate_limit_exceeded",
"quota_exceeded",
"temporarily_unavailable",
"internal_error"
]
},
"message": {
"type": "string"
},
"request_id": {
"type": "string",
"pattern": "^req_[a-zA-Z0-9_-]+$"
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
"required": [
"code",
"message",
"request_id",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false,
"description": "No secrets, SQL, or stack traces. retry_after_seconds is non-null for 429/503 and matches Retry-After. Retry rate/503 with bounded backoff and jitter; quota retry waits until period_end or explicit upgrade. 401/403/400/409 are not blind-retryable."
}Possible errors
Every error below uses the Error envelope with a request ID. Retry only when the response’s proposed semantics identify a temporary condition; see errors and versioning for the detailed guidance.
400 synthetic error example
Invalid or unknown parameter/body, duplicated query parameter, malformed or expired cursor.
X-Request-Id — Request correlation identifier; safe to send to support. X-Request-Credits-Remaining — Organization credits remaining after this request. Present only after successful key authentication. X-Request-Credits-Charged — 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. Cache-Control — private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate.
{
"error": {
"code": "invalid_request",
"message": "Synthetic example: Invalid or unknown parameter/body, duplicated query parameter, malformed or expired cursor.",
"request_id": "req_example",
"retry_after_seconds": null
}
}401 synthetic error example
Missing, invalid, expired or revoked API key.
X-Request-Id — Request correlation identifier; safe to send to support. X-Request-Credits-Remaining — Organization credits remaining after this request. Present only after successful key authentication. X-Request-Credits-Charged — 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. Cache-Control — private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate.
{
"error": {
"code": "invalid_api_key",
"message": "Synthetic example: Missing, invalid, expired or revoked API key.",
"request_id": "req_example",
"retry_after_seconds": null
}
}403 synthetic error example
Authenticated key lacks endpoint scope or entitlement.
X-Request-Id — Request correlation identifier; safe to send to support. X-Request-Credits-Remaining — Organization credits remaining after this request. Present only after successful key authentication. X-Request-Credits-Charged — 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. Cache-Control — private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate.
{
"error": {
"code": "insufficient_scope",
"message": "Synthetic example: Authenticated key lacks endpoint scope or entitlement.",
"request_id": "req_example",
"retry_after_seconds": null
}
}429 synthetic error example
rate_limit_exceeded or quota_exceeded; distinct codes and Retry-After.
X-Request-Id — Request correlation identifier; safe to send to support. X-Request-Credits-Remaining — Organization credits remaining after this request. Present only after successful key authentication. X-Request-Credits-Charged — 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. Cache-Control — private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate. Retry-After — Whole seconds until retry.
{
"error": {
"code": "rate_limit_exceeded",
"message": "Synthetic example: rate_limit_exceeded or quota_exceeded; distinct codes and Retry-After.",
"request_id": "req_example",
"retry_after_seconds": 60
}
}500 synthetic error example
Unexpected internal failure; no sensitive details and zero credits.
X-Request-Id — Request correlation identifier; safe to send to support. X-Request-Credits-Remaining — Organization credits remaining after this request. Present only after successful key authentication. X-Request-Credits-Charged — 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. Cache-Control — private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate.
{
"error": {
"code": "internal_error",
"message": "Synthetic example: Unexpected internal failure; no sensitive details and zero credits.",
"request_id": "req_example",
"retry_after_seconds": null
}
}503 synthetic error example
temporarily_unavailable: metering, key state, or serving dependency unavailable; fail closed and charge zero.
X-Request-Id — Request correlation identifier; safe to send to support. X-Request-Credits-Remaining — Organization credits remaining after this request. Present only after successful key authentication. X-Request-Credits-Charged — 0 or 1 for this response; internal cache hits count, idempotent batch replays do not. Cache-Control — private, no-store; key-specific metadata must never enter a shared HTTP cache. Server-side data caching is separate. Retry-After — Whole seconds until retry.
{
"error": {
"code": "temporarily_unavailable",
"message": "Synthetic example: temporarily_unavailable: metering, key state, or serving dependency unavailable; fail closed and charge zero.",
"request_id": "req_example",
"retry_after_seconds": 30
}
}