Get Usage Summary
curl --request GET \
--url https://api.signa.so/v1/organization/usage/summary \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.signa.so/v1/organization/usage/summary"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.signa.so/v1/organization/usage/summary', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.signa.so/v1/organization/usage/summary",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.signa.so/v1/organization/usage/summary"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.signa.so/v1/organization/usage/summary")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.signa.so/v1/organization/usage/summary")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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"
}
Usage & Credits
Get Usage Summary
Daily usage breakdown for the organization
GET
/
v1
/
organization
/
usage
/
summary
Get Usage Summary
curl --request GET \
--url https://api.signa.so/v1/organization/usage/summary \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.signa.so/v1/organization/usage/summary"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.signa.so/v1/organization/usage/summary', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.signa.so/v1/organization/usage/summary",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.signa.so/v1/organization/usage/summary"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.signa.so/v1/organization/usage/summary")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.signa.so/v1/organization/usage/summary")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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"
}
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 byday, 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
string
required
Start of date range (
YYYY-MM-DD).string
required
End of date range (
YYYY-MM-DD), inclusive.string
default:"day"
Grouping dimension. One of
day, endpoint_type, or api_key.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.credits_limit reflects that endpoint type’s specific plan allowance.Response
string
Always
"list".object[]
Show Usage summary item
Show Usage summary item
string
ISO timestamp for the start of the rollup period (usually a day).
string
Endpoint type for this row.
string
API key ID (
key_...). Present only when group_by=api_key.integer
Total requests in the period.
integer
Credits consumed by billable requests in the period.
integer
Count of non-2xx responses in the period.
integer
Average request duration in milliseconds (null if no requests).
boolean
Always
false — the summary is fully returned in one response.object
Show Current billing period context
Show Current billing period context
string
ISO timestamp for the billing period start (inclusive).
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).integer
Credits used so far this billing period (overall, or for the filtered endpoint type).
integer | null
Pooled credit allowance for the period (
null if unlimited).integer | null
credits_limit - credits_used, floored at 0 (null if unlimited).boolean
true when the date range fell back to the current billing period because both start_date and end_date were omitted.string
Request ID for debugging.
{
"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
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"
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",
});
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 — current billing period totals by endpoint type
- List Request Logs — per-request audit trail