Get Usage

Retrieve API usage statistics for the current billing period

GET /v1/organization/usage

Get Usage

cURL

curl --request GET \
  --url https://api.signa.so/v1/organization/usage \
  --header 'Authorization: Bearer <token>'

{
  "object": "usage",
  "billing_period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-30T23:59:59Z"
  },
  "by_endpoint_type": {
    "search": { "used": 1204, "limit": 100000 },
    "read": { "used": 8932, "limit": 500000 }
  },
  "rate_limit": {
    "limit": 1000,
    "resets_at": "2026-04-18T12:30:00Z"
  },
  "rate_limits": {
    "search": 1000,
    "read": 10000,
    "monitoring": 100,
    "utility": 1000,
    "reference": 1000,
    "check": 1000
  },
  "request_id": "req_abc123"
}

Overview

Returns API usage statistics for the current billing period, broken down by endpoint type, plus the per-endpoint-type rate-limit matrix. The by_endpoint_type object reports used and limit for every shipped metered endpoint type — today that is exactly search and read. Pools without shipped endpoints (screening, clearance, image_search, export) do not appear until their routes ship. The check pool is shipped and quota-metered (POST /v1/goods-services/suggest — watch the X-Quota-* headers on those responses) but not yet itemized in by_endpoint_type or /v1/organization/plan. A limit of null indicates an unlimited plan; 0 means the endpoint type is not allowed on the current plan.

Requires the billing:read scope (keys created from the dashboard have it by default).

Response

object · string

Always "usage"

billing_period · object

Show Billing period

start · string

ISO timestamp for the billing period start

end · string

ISO timestamp for the billing period end

by_endpoint_type · object

Show Per-endpoint-type usage

Keyed by shipped metered endpoint type (currently search and read). Each value is an object:

rate_limit · object · deprecated

Show Rate limit status (deprecated)

Deprecated — reflects the search-tier RPM only (1,000/min on beta), which disagrees with the RateLimit-Policy header on non-search endpoints. Use rate_limits instead. Retained for backward compatibility.

rate_limits · object

Per-endpoint-type requests-per-minute matrix — what the rate limiter actually enforces per classification (search, read, monitoring, utility, reference, check). See Rate Limits.

request_id · string

Request ID for debugging

{
  "object": "usage",
  "billing_period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-30T23:59:59Z"
  },
  "by_endpoint_type": {
    "search": { "used": 1204, "limit": 100000 },
    "read": { "used": 8932, "limit": 500000 }
  },
  "rate_limit": {
    "limit": 1000,
    "resets_at": "2026-04-18T12:30:00Z"
  },
  "rate_limits": {
    "search": 1000,
    "read": 10000,
    "monitoring": 100,
    "utility": 1000,
    "reference": 1000,
    "check": 1000
  },
  "request_id": "req_abc123"
}

Code Examples

cURL

curl "https://api.signa.so/v1/organization/usage" \
  -H "Authorization: Bearer sig_xxxxxxxxxxxx"

Errors

Status	Type	Description
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks the billing:read scope
429	rate_limited	Too many requests

Related Endpoints

• Get Current Organization — organization profile and plan
• Get Usage Summary — daily breakdown by endpoint type or API key
• List API Keys — manage API keys