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"
}

GET

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 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.credits_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.

credits

integer

Credits consumed by billable requests 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).

credits_used

integer

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

credits_limit

integer | null

Pooled credit allowance for the period (null if unlimited).

credits_remaining

integer | null

credits_limit - credits_used, floored at 0 (null if unlimited).

defaulted

boolean

true when the date range fell back to the current billing period because both start_date and end_date were omitted.

request_id

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

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

Get Usage Get Credits

Overview

Trademarks

Parties

Records

Monitoring

Reference

Analytics

Bulk & Sync

Administration

SDK

Get Usage Summary

Overview

Query Parameters

Response

Code Examples

Errors

​Overview

​Query Parameters

​Response

​Code Examples

​Errors

​Related Endpoints

Overview

Query Parameters

Response

Code Examples

Errors

Related Endpoints