Get Usage Summary

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 (e.g. search, read, screening, clearance, image_search, check, export). 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 "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

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

Overview

Trademarks

Parties

Reference

Administration

Overview

Query Parameters

Response

Code Examples

Errors

Overview

Trademarks

Parties

Reference

Administration

​Overview

​Query Parameters

​Response

​Code Examples

​Errors

​Related Endpoints

Overview

Query Parameters

Response

Code Examples

Errors

Related Endpoints