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

> Your recorded traffic priced at the published credit schedule

<Note>
  **Beta.** This is an *estimate* of what past traffic would cost on the published credit schedule — not a bill, an invoice, or a commitment. The response shape may still change.
</Note>

## Overview

Prices the authenticated organization's recorded API traffic at the published credit schedule and shows which plan that traffic lands on. Use it to answer "what would last month have cost" before anything is charged.

Requests recorded *before* the credit cutover carry the old placeholder weights, so they are re-priced from their route; requests recorded after it already carry credits and are reported at face value. Traffic the launch beta gives away is metered at its full list price and reported separately under `credits.beta_free`, so `credits.charged` is always what you would actually pay.

`plan_for`, `packs_needed` and `offer` are derived from `credits.per_month` — the window scaled to 30 days — so a two-day window and a quarter recommend comparable plans rather than plans two sizes apart.

Defaults to the last 30 days. Requires the `billing:read` scope. Querying the estimate is not billed.

## Query Parameters

<ParamField query="from" type="string">
  Start of the window (`YYYY-MM-DD`). Must be provided together with `to`. Omit both for the last 30 days.
</ParamField>

<ParamField query="to" type="string">
  End of the window (`YYYY-MM-DD`), inclusive. Must be provided together with `from`, may not be in the future, and the window may not exceed 92 days. Today is accepted; the window then ends at the moment you ask, so the projection divides only by time that has elapsed.
</ParamField>

## Response

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

<ResponseField name="period" type="object">
  <Expandable title="Window priced">
    <ResponseField name="from" type="string">ISO timestamp, inclusive.</ResponseField>
    <ResponseField name="to" type="string">ISO timestamp, exclusive. Never later than the moment of the request: a window ending today ends now, not at tomorrow's midnight.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule_version" type="integer">Version of the credit schedule used to price the window.</ResponseField>

<ResponseField name="credits" type="object">
  <Expandable title="Credit totals">
    <ResponseField name="charged" type="integer">What this traffic would cost you.</ResponseField>
    <ResponseField name="nominal" type="integer">The same traffic at list price, including anything the beta waives.</ResponseField>
    <ResponseField name="beta_free" type="integer">List-price credits waived by the launch beta (`nominal - charged`).</ResponseField>
    <ResponseField name="per_month" type="object">The same three totals scaled to a 30-day month. Everything about the plan is decided on these, because a pooled monthly allowance can only be compared to a monthly figure.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requests" type="object">
  <Expandable title="Request counts">
    <ResponseField name="total" type="integer">Requests recorded in the window, billable or not.</ResponseField>
    <ResponseField name="unrouted" type="integer">Authenticated requests that matched no route (404s).</ResponseField>
    <ResponseField name="unmapped" type="integer">Requests on a route the schedule does not recognize. Reported, never silently priced at zero.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="by_action" type="object[]">
  <Expandable title="Per-action breakdown, most expensive first">
    <ResponseField name="action_id" type="string">Schedule action id (e.g. `search`), or a synthetic bucket: `unmapped`, `unrouted`, `removed:<path>`, `unpriced:<path>`, `free:<type>`.</ResponseField>
    <ResponseField name="name" type="string">Human name for the action.</ResponseField>
    <ResponseField name="requests" type="integer">Requests in this bucket.</ResponseField>
    <ResponseField name="quantity" type="number">Charged quantity in the action's own unit (pages, records, items, requests).</ResponseField>
    <ResponseField name="credits" type="integer">Credits you would be charged.</ResponseField>
    <ResponseField name="nominal_credits" type="integer">The same rows at list price.</ResponseField>
    <ResponseField name="disposition" type="string">`charged`, `beta_free` (metered, never debited), `free` (zero-price or non-billable), `mixed` (both, for a window spanning a change), or `unpriced`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="unmapped" type="object[]">
  <Expandable title="Routes the schedule does not recognize">
    <ResponseField name="route" type="string">Route pattern as recorded.</ResponseField>
    <ResponseField name="method" type="string">HTTP method.</ResponseField>
    <ResponseField name="endpoint_type" type="string">Endpoint type the request was billed under at the time.</ResponseField>
    <ResponseField name="requests" type="integer">Requests on this route.</ResponseField>
    <ResponseField name="credits" type="integer">Credits they actually cost.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="plan_for" type="object | null">
  <Expandable title="Smallest plan that fits the projected month">
    <ResponseField name="id" type="string">Plan id (`free`, `starter`, `growth`, `scale`).</ResponseField>
    <ResponseField name="name" type="string">Plan name.</ResponseField>
    <ResponseField name="credits_included" type="integer | null">Pooled credits per month.</ResponseField>
    <ResponseField name="per_month_annual" type="number | null">Price per month when billed yearly, USD.</ResponseField>
    <ResponseField name="monthly" type="number | null">Price per month when billed monthly, USD.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="packs_needed" type="object | null">
  <Expandable title="Top-up packs the plan needs on top of its pool">
    <ResponseField name="credits" type="integer">Pack credits bought.</ResponseField>
    <ResponseField name="count" type="integer">How many of the plan's top-up packs.</ResponseField>
    <ResponseField name="usd" type="number">What they cost, USD.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="above_self_serve" type="boolean">`true` when the projected month is beyond what the plan ladder plus top-up packs sells; `plan_for` is then `null` and the right next step is a conversation.</ResponseField>

<ResponseField name="offer" type="object | null">
  <Expandable title="Beta thank-you discount on that plan">
    <ResponseField name="percent_off" type="number">Discount percentage.</ResponseField>
    <ResponseField name="months" type="integer">How many months it runs.</ResponseField>
    <ResponseField name="price_per_month" type="number">The annual per-month price with the discount applied, USD.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="coverage" type="object">
  <Expandable title="What the estimate cannot see">
    <ResponseField name="pre_cutover_unmetered_actions" type="string[]">Actions with no recorded volume before the cutover, because their routes were free and unmetered then.</ResponseField>
    <ResponseField name="note" type="string">Plain-language explanation of the gap.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string">Request ID for debugging.</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "usage_estimate",
    "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-09-01T00:00:00.000Z" },
    "schedule_version": 2,
    "credits": {
      "charged": 31500,
      "nominal": 33500,
      "beta_free": 2000,
      "per_month": { "charged": 30484, "nominal": 32419, "beta_free": 1935 }
    },
    "requests": { "total": 3155, "unrouted": 2, "unmapped": 0 },
    "by_action": [
      {
        "action_id": "search",
        "name": "Search",
        "requests": 3000,
        "quantity": 3000,
        "credits": 30000,
        "nominal_credits": 30000,
        "disposition": "charged"
      },
      {
        "action_id": "read",
        "name": "Retrieve",
        "requests": 153,
        "quantity": 1500,
        "credits": 1500,
        "nominal_credits": 1500,
        "disposition": "charged"
      },
      {
        "action_id": "screen",
        "name": "Screening",
        "requests": 2,
        "quantity": 2,
        "credits": 0,
        "nominal_credits": 2000,
        "disposition": "beta_free"
      }
    ],
    "unmapped": [],
    "plan_for": {
      "id": "growth",
      "name": "Growth",
      "credits_included": 100000,
      "per_month_annual": 399,
      "monthly": 529
    },
    "packs_needed": null,
    "above_self_serve": false,
    "offer": { "percent_off": 25, "months": 12, "price_per_month": 299.25 },
    "coverage": {
      "pre_cutover_unmetered_actions": ["class_lookup", "rules_lookup"],
      "note": "Class and rules lookups are free reference routes today and are not written to billing_events, so any part of this window before the cutover cannot show their volume."
    },
    "request_id": "req_abc123"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/organization/usage/estimate?from=2026-08-01&to=2026-08-31" \
    -H "Authorization: Bearer sig_xxxxxxxxxxxx"
  ```

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

  const signa = new Signa({ api_key: "sig_xxxxxxxxxxxx" });

  const estimate = await signa.organization.usageEstimate({
    from: "2026-08-01",
    to: "2026-08-31",
  });
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.signa.so/v1/organization/usage/estimate",
      headers={"Authorization": "Bearer sig_xxxxxxxxxxxx"},
      params={"from": "2026-08-01", "to": "2026-08-31"},
  )
  estimate = resp.json()
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                                                                                                             |
| ------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `validation_error` | `from`/`to` not given together, invalid date, `from > to`, `to` in the future, or a window wider than 92 days                                                           |
| 401    | `unauthorized`     | Missing or invalid API key                                                                                                                                              |
| 403    | `forbidden`        | API key lacks `billing:read`                                                                                                                                            |
| 429    | `rate_limited`     | Too many requests                                                                                                                                                       |
| 504    | `timeout`          | The aggregate did not finish inside the read pool's statement timeout. Narrow the window and retry -- a wide window over a high-volume organization is the usual cause. |

## Related Endpoints

* [Get Usage Summary](/api-reference/administration/get-usage-summary) -- daily breakdown from pre-aggregated rollups
* [Get Usage](/api-reference/administration/get-usage) -- current billing period totals by endpoint type
* [Get Credits](/api-reference/administration/get-credits) -- pooled credit balance