> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Usage Summary
> Daily usage breakdown for the organization
**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 of date range (`YYYY-MM-DD`).
End of date range (`YYYY-MM-DD`), inclusive.
Grouping dimension. One of `day`, `endpoint_type`, or `api_key`.
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.credits_limit` reflects that endpoint type's specific plan allowance.
## Response
Always `"list"`.
ISO timestamp for the start of the rollup period (usually a day).
Endpoint type for this row.
API key ID (`key_...`). Present only when `group_by=api_key`.
Total requests in the period.
Credits consumed by billable requests in the period.
Count of non-2xx responses in the period.
Average request duration in milliseconds (null if no requests).
Always `false` -- the summary is fully returned in one response.
ISO timestamp for the billing period start (inclusive).
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).
Credits used so far this billing period (overall, or for the filtered endpoint type).
Pooled credit allowance for the period (`null` if unlimited).
`credits_limit - credits_used`, floored at 0 (`null` if unlimited).
`true` when the date range fell back to the current billing period because both `start_date` and `end_date` were omitted.
Request ID for debugging.
```json theme={null}
{
"object": "list",
"data": [
{
"period_start": "2026-04-15T00:00:00Z",
"endpoint_type": "search",
"request_count": 420,
"credits": 420,
"error_count": 2,
"avg_duration_ms": 138
},
{
"period_start": "2026-04-16T00:00:00Z",
"endpoint_type": "search",
"request_count": 512,
"credits": 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",
"credits_used": 932,
"credits_limit": 100000,
"credits_remaining": 99068,
"defaulted": false
},
"request_id": "req_abc123"
}
```
## Code Examples
```bash cURL theme={null}
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"
```
```typescript TypeScript theme={null}
import { Signa } from "@signa-so/sdk";
const signa = new Signa({ api_key: "sig_xxxxxxxxxxxx" });
const summary = await signa.organization.usageSummary({
start_date: "2026-04-01",
end_date: "2026-04-18",
group_by: "day",
endpoint_type: "search",
});
```
```python Python theme={null}
import requests
resp = requests.get(
"https://api.signa.so/v1/organization/usage/summary",
headers={"Authorization": "Bearer sig_xxxxxxxxxxxx"},
params={
"start_date": "2026-04-01",
"end_date": "2026-04-18",
"group_by": "day",
"endpoint_type": "search",
},
)
summary = resp.json()
```
## 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](/api-reference/administration/get-usage) -- current billing period totals by endpoint type
* [List Request Logs](/api-reference/administration/get-logs) -- per-request audit trail