> ## 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

> Retrieve API usage statistics for the current billing period

## Overview

Returns API usage for the current billing period, broken down by metered endpoint type, plus the per-endpoint-type requests-per-minute limits your plan enforces.

`by_endpoint_type` reports `used` and `limit` for each metered endpoint type: `search`, `read`, `screening`, and `check`. A `limit` of `null` means unlimited on your plan; `0` means the endpoint type is not available on your plan.

Requires the `billing:read` scope.

## Response

<ResponseField name="object" type="string">Always `usage`.</ResponseField>

<ResponseField name="billing_period" type="object">
  <Expandable title="Billing period">
    <ResponseField name="start" type="string">ISO timestamp for the billing period start (inclusive).</ResponseField>
    <ResponseField name="end" type="string">ISO timestamp for the billing period end (exclusive).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="by_endpoint_type" type="object">
  <Expandable title="Per-endpoint-type usage">
    Keyed by metered endpoint type (`search`, `read`, `screening`, `check`). Each value is an object:
    <ResponseField name="used" type="integer">Units used in the current billing period for this endpoint type.</ResponseField>
    <ResponseField name="limit" type="integer | null">Plan limit for this endpoint type. `null` if unlimited, `0` if not available on the current plan.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rate_limits" type="object">
  Requests-per-minute limit per endpoint type (`search`, `read`, `screening`, `monitoring`, `utility`, `reference`, `check`), as enforced by the rate limiter. See [Rate Limits](/api-reference/rate-limits) for how limits are applied.
</ResponseField>

<ResponseField name="request_id" type="string">Unique request identifier for support and debugging.</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "usage",
    "billing_period": {
      "start": "2026-06-01T00:00:00.000Z",
      "end": "2026-07-01T00:00:00.000Z"
    },
    "by_endpoint_type": {
      "search": { "used": 1204, "limit": 100000 },
      "read": { "used": 8932, "limit": 500000 },
      "screening": { "used": 112, "limit": 1000 },
      "check": { "used": 46, "limit": 500000 }
    },
    "rate_limits": {
      "search": 1000,
      "read": 10000,
      "screening": 100,
      "monitoring": 100,
      "utility": 1000,
      "reference": 1000,
      "check": 1000
    },
    "request_id": "req_aS6kL2mN"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/organization/usage" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const usage = await signa.organization.usage();
  console.log("Search used:", usage.by_endpoint_type.search.used);
  ```
</CodeGroup>

## Errors

| Status | Type           | Description                            |
| ------ | -------------- | -------------------------------------- |
| 401    | `unauthorized` | Missing or invalid API key             |
| 403    | `forbidden`    | API key lacks the `billing:read` scope |
| 429    | `rate_limited` | Too many requests                      |

## Related Endpoints

* [Get Current Organization](/api-reference/administration/get-me), organization profile and plan
* [Get Usage Summary](/api-reference/administration/get-usage-summary), daily breakdown by endpoint type or API key
* [List API Keys](/api-reference/administration/list-api-keys), manage API keys