Get Usage Summary

Daily usage breakdown for the organization

GET /v1/organization/usage/summary

Get Usage Summary

cURL

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

{
  "object": "list",
  "data": [
    {
      "period_start": "2026-04-15T00:00:00Z",
      "endpoint_type": "search",
      "request_count": 420,
      "billed_units": 420,
      "error_count": 2,
      "avg_duration_ms": 138
    },
    {
      "period_start": "2026-04-16T00:00:00Z",
      "endpoint_type": "search",
      "request_count": 512,
      "billed_units": 512,
      "error_count": 0,
      "avg_duration_ms": 121
    }
  ],
  "has_more": false,
  "billing_period": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-05-01T00:00:00.000Z",
    "quota_used": 932,
    "quota_limit": 100000,
    "quota_remaining": 99068
  },
  "request_id": "req_abc123"
}

Beta. The usage summary schema is new and may evolve. Field names should be stable, but we reserve the right to add fields or adjust response shape before general availability.

Overview

Returns a pre-aggregated usage breakdown for the authenticated organization over a date range. Reads from daily rollups for fast queries, then attaches the current billing period’s quota status.

Group the results by day, endpoint_type, or api_key, and optionally filter to a single endpoint type. Requires the billing:read scope. Querying the summary does not consume metered usage.

Query Parameters

start_date · string · required

Start of date range (YYYY-MM-DD).

end_date · string · required

End of date range (YYYY-MM-DD), inclusive.

group_by · string · default: "day"

Grouping dimension. One of day, endpoint_type, or api_key.

endpoint_type · string

Restrict the summary to a specific endpoint type. Itemized metered types are search and read. check is shipped and quota-metered (POST /v1/goods-services/suggest) but not yet itemized here; others — screening, clearance, image_search, export — exist in plan config but have no shipped endpoints yet. When set, the billing_period.quota_limit reflects that endpoint type’s specific plan allowance.

Response

object · string

Always "list".

data · object[]

Show Usage summary item

period_start · string

ISO timestamp for the start of the rollup period (usually a day).

endpoint_type · string

Endpoint type for this row.

api_key_id · string

API key ID (key_...). Present only when group_by=api_key.

request_count · integer

Total requests in the period.

billed_units · integer

Billed units accrued in the period.

error_count · integer

Count of non-2xx responses in the period.

avg_duration_ms · integer

Average request duration in milliseconds (null if no requests).

has_more · boolean

Always false — the summary is fully returned in one response.

billing_period · object

Show Current billing period context

start · string

ISO timestamp for the billing period start (inclusive).

end · string

ISO timestamp for the billing period end (exclusive — this is the start of the next period, e.g. 2026-05-01T00:00:00.000Z for an April period).

quota_used · integer

Units used so far this billing period (overall, or for the filtered endpoint type).

quota_limit · integer | null

Plan quota for the period (null if unlimited).

quota_remaining · integer | null

quota_limit - quota_used, floored at 0 (null if unlimited).

request_id · string

Request ID for debugging.

{
  "object": "list",
  "data": [
    {
      "period_start": "2026-04-15T00:00:00Z",
      "endpoint_type": "search",
      "request_count": 420,
      "billed_units": 420,
      "error_count": 2,
      "avg_duration_ms": 138
    },
    {
      "period_start": "2026-04-16T00:00:00Z",
      "endpoint_type": "search",
      "request_count": 512,
      "billed_units": 512,
      "error_count": 0,
      "avg_duration_ms": 121
    }
  ],
  "has_more": false,
  "billing_period": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-05-01T00:00:00.000Z",
    "quota_used": 932,
    "quota_limit": 100000,
    "quota_remaining": 99068
  },
  "request_id": "req_abc123"
}

Code Examples

cURL

curl "https://api.signa.so/v1/organization/usage/summary?start_date=2026-04-01&end_date=2026-04-18&group_by=day&endpoint_type=search" \
  -H "Authorization: Bearer sig_xxxxxxxxxxxx"

Errors

Status	Type	Description
400	validation_error	Missing start_date/end_date, invalid date format, or start_date > end_date
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks billing:read
429	rate_limited	Too many requests

Related Endpoints

• Get Usage — current billing period totals by endpoint type
• List Request Logs — per-request audit trail