> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runpulse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Usage

> Programmatic counterpart to the platform usage dashboard. Returns the
calling organization's current billing-period credit status plus
document, page, and credit totals with a bucketed timeline over the
requested window (default: the last 30 days; maximum window: 366 days).

The response is always scoped to the organization the credentials
belong to. There is no way to request another organization's usage:
any organization identifier supplied by the caller is ignored, and
the response contains no identifiers of any kind.

## Overview

Retrieve your organization's usage programmatically — the same figures shown on the [platform usage dashboard](https://platform.runpulse.com/dashboard/usage). One call returns three things:

* **`billing`** — where your current billing period stands: plan, credit allowance, credits used and remaining, overage, and metered-cost estimates.
* **`totals`** — documents, pages, and credits consumed over the requested window.
* **`by_period`** — the same consumption bucketed by `day`, `week`, or `month`, ready to chart or feed into internal reporting.

Authentication uses your regular API key (`x-api-key`), and the response is always scoped to the organization that key belongs to — organization identifiers supplied in the query string are ignored, and the response contains no identifiers of any kind.

<Note>
  `billing` reflects your **current billing period** regardless of the requested window. `totals` and `by_period` cover exactly the `from`→`to` window.
</Note>

## Choosing a window

* Both dates accept `YYYY-MM-DD` or a full ISO 8601 datetime.
* With no parameters, the window is the **last 30 days**.
* A date-only `to` is inclusive: `to=2026-07-14` covers all of July 14 (UTC).
* The maximum window is **366 days**; longer windows return a `400`.
* `by_period` buckets are UTC calendar periods, sorted ascending. Periods with no usage are omitted rather than returned as zero rows — pad them client-side if your charting needs continuous axes.

## Response

```json theme={null}
{
  "from": "2026-07-10T00:00:00+00:00",
  "to": "2026-07-14T23:59:59.999999+00:00",
  "group_by": "day",
  "generated_at": "2026-07-15T18:04:11+00:00",
  "billing": {
    "plan_name": "Growth",
    "billing_type": "subscription",
    "period_start": "2026-07-01T00:00:00+00:00",
    "period_end": "2026-08-01T00:00:00+00:00",
    "credits_used": 12451.5,
    "credit_allowance": 50000.0,
    "credits_remaining": 37548.5,
    "overage_credits": 0.0,
    "usage_percentage": 24.9,
    "limit_exceeded": false,
    "is_metered": false,
    "metered_rate": null,
    "estimated_cost": null,
    "overage_cost": null
  },
  "totals": {
    "documents": 611,
    "pages": 3720,
    "credits": 4184.0
  },
  "by_period": [
    { "period": "2026-07-10T00:00:00+00:00", "documents": 130, "pages": 708, "credits": 803.0 },
    { "period": "2026-07-11T00:00:00+00:00", "documents": 136, "pages": 814, "credits": 887.5 },
    { "period": "2026-07-12T00:00:00+00:00", "documents": 136, "pages": 814, "credits": 887.5 },
    { "period": "2026-07-13T00:00:00+00:00", "documents": 111, "pages": 666, "credits": 720.0 },
    { "period": "2026-07-14T00:00:00+00:00", "documents": 98, "pages": 718, "credits": 886.0 }
  ]
}
```

### `billing` fields

| Field                         | Type           | Description                                                                                   |
| ----------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `plan_name`                   | string \| null | Name of your plan.                                                                            |
| `billing_type`                | string         | `subscription`, `pay_as_you_go`, `free`, or `unknown`.                                        |
| `period_start` / `period_end` | string \| null | Billing period bounds (ISO 8601, UTC), when the plan defines them.                            |
| `credits_used`                | number         | Credits consumed in the current billing period.                                               |
| `credit_allowance`            | number \| null | Credits included in the plan; `null` when unlimited.                                          |
| `credits_remaining`           | number \| null | Allowance left; `null` when unlimited.                                                        |
| `overage_credits`             | number         | Credits consumed beyond the allowance.                                                        |
| `usage_percentage`            | number \| null | Share of the allowance consumed; `null` when the plan has no allowance.                       |
| `limit_exceeded`              | boolean        | Whether the allowance has been reached or exceeded.                                           |
| `is_metered`                  | boolean        | Whether the plan bills per credit consumed.                                                   |
| `metered_rate`                | number \| null | Price per credit. `null` unless `is_metered` is true.                                         |
| `estimated_cost`              | number \| null | Estimated period cost on metered plans with no allowance. `null` unless `is_metered` is true. |
| `overage_cost`                | number \| null | Estimated cost of overage credits. `null` unless `is_metered` is true.                        |

Fields that don't apply to your plan are `null`: `credit_allowance` on pure metered billing, and every metered pricing field whenever `is_metered` is false.

### `totals` and `by_period` fields

| Field       | Type    | Description                                                                                                           |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `documents` | integer | Documents processed.                                                                                                  |
| `pages`     | integer | Pages processed.                                                                                                      |
| `credits`   | number  | Credits consumed — see [Credit Usage](/api-reference/introduction#credit-usage) for how each pipeline step is billed. |
| `period`    | string  | Bucket start (ISO 8601, UTC). `by_period` entries only.                                                               |

## Examples

Last 30 days at daily resolution (all defaults):

```bash theme={null}
curl -H "x-api-key: $PULSE_API_KEY" "https://api.runpulse.com/usage"
```

A specific month, bucketed by week:

```bash theme={null}
curl -H "x-api-key: $PULSE_API_KEY" \
  "https://api.runpulse.com/usage?from=2026-06-01&to=2026-06-30&group_by=week"
```

Alerting when the billing period runs hot:

```python theme={null}
import requests

usage = requests.get(
    "https://api.runpulse.com/usage",
    headers={"x-api-key": PULSE_API_KEY},
).json()

billing = usage["billing"]
if billing["usage_percentage"] and billing["usage_percentage"] > 80:
    alert(f"{billing['credits_remaining']} credits left this billing period")

for bucket in usage["by_period"]:
    print(f"{bucket['period'][:10]}: {bucket['documents']} docs, {bucket['credits']} credits")
```

## Errors

| Status | Meaning                                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Malformed `from`/`to`, window end before start, window longer than 366 days, or unknown `group_by`. Details are included in the response body. |
| `401`  | Missing or invalid API key.                                                                                                                    |
| `429`  | Organization rate limit exceeded.                                                                                                              |
| `500`  | Usage aggregation failed.                                                                                                                      |


## OpenAPI

````yaml GET /usage
openapi: 3.1.0
info:
  title: Pulse API Structure
  version: 0.1.0
  description: >-
    Canonical contract for the Pulse extraction APIs. This specification is the
    single source of truth for shared request/response models that client and
    server packages consume.
servers:
  - url: https://api.runpulse.com
    description: Default Pulse API base URL
security:
  - ApiKey: []
paths:
  /usage:
    get:
      tags:
        - Usage
      summary: Retrieve organization usage and credit status
      description: |-
        Programmatic counterpart to the platform usage dashboard. Returns the
        calling organization's current billing-period credit status plus
        document, page, and credit totals with a bucketed timeline over the
        requested window (default: the last 30 days; maximum window: 366 days).

        The response is always scoped to the organization the credentials
        belong to. There is no way to request another organization's usage:
        any organization identifier supplied by the caller is ignored, and
        the response contains no identifiers of any kind.
      operationId: getUsage
      parameters:
        - name: from
          in: query
          required: false
          description: >-
            Window start as `YYYY-MM-DD` or an ISO 8601 datetime. Defaults to 30
            days before `to`.
          schema:
            type: string
            example: '2026-07-10'
        - name: to
          in: query
          required: false
          description: >-
            Window end as `YYYY-MM-DD` or an ISO 8601 datetime. A date-only
            value is inclusive — it extends to the end of that day (UTC).
            Defaults to the current time.
          schema:
            type: string
            example: '2026-07-14'
        - name: group_by
          in: query
          required: false
          description: Bucket size for the `by_period` timeline.
          schema:
            type: string
            enum:
              - day
              - week
              - month
            default: day
      responses:
        '200':
          description: Usage summary for the calling organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          description: >-
            Malformed `from`/`to`, window end before start, window longer than
            366 days, or unknown `group_by` value
        '401':
          description: Authentication failed or missing API key
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
components:
  schemas:
    UsageResponse:
      type: object
      description: >-
        Organization usage summary: current billing-period credit status plus
        totals and a bucketed timeline for the requested window. Matches the
        figures shown on the platform usage dashboard.
      required:
        - from
        - to
        - group_by
        - generated_at
        - billing
        - totals
        - by_period
      properties:
        from:
          type: string
          format: date-time
          description: Resolved window start (UTC).
        to:
          type: string
          format: date-time
          description: Resolved window end (UTC, inclusive).
        group_by:
          type: string
          enum:
            - day
            - week
            - month
          description: Bucket size used for `by_period`.
        generated_at:
          type: string
          format: date-time
          description: When this summary was computed.
        billing:
          $ref: '#/components/schemas/UsageBillingSummary'
        totals:
          $ref: '#/components/schemas/UsageWindowTotals'
        by_period:
          type: array
          description: >-
            Usage bucketed by `group_by`, ascending. Periods with no usage are
            omitted rather than returned as zero rows.
          items:
            $ref: '#/components/schemas/UsagePeriodBucket'
    UsageBillingSummary:
      type: object
      description: >-
        Where the organization's current billing period stands. Reflects the
        active plan and billing cycle regardless of the requested window. Fields
        that don't apply to the plan are null — the allowance on pure metered
        billing, and every metered pricing field (`metered_rate`,
        `estimated_cost`, `overage_cost`) unless `is_metered` is true.
      required:
        - billing_type
        - credits_used
        - overage_credits
        - limit_exceeded
        - is_metered
      properties:
        plan_name:
          type: string
          nullable: true
          description: Name of the organization's plan.
        billing_type:
          type: string
          description: >-
            Billing model — `subscription`, `pay_as_you_go`, `free`, or
            `unknown`.
        period_start:
          type: string
          format: date-time
          nullable: true
          description: Billing period start (UTC), when the plan defines one.
        period_end:
          type: string
          format: date-time
          nullable: true
          description: Billing period end (UTC), when the plan defines one.
        credits_used:
          type: number
          description: Credits consumed in the current billing period.
        credit_allowance:
          type: number
          nullable: true
          description: Credits included in the plan; null when unlimited.
        credits_remaining:
          type: number
          nullable: true
          description: Credits left in the allowance; null when unlimited.
        overage_credits:
          type: number
          description: Credits consumed beyond the allowance.
        usage_percentage:
          type: number
          nullable: true
          description: >-
            Share of the allowance consumed, as a percentage; null when the plan
            has no allowance.
        limit_exceeded:
          type: boolean
          description: Whether the allowance has been reached or exceeded.
        is_metered:
          type: boolean
          description: Whether the plan bills per credit consumed.
        metered_rate:
          type: number
          nullable: true
          description: Price per credit. Null unless `is_metered` is true.
        estimated_cost:
          type: number
          nullable: true
          description: >-
            Estimated cost for the current period on metered plans with no
            allowance. Null unless `is_metered` is true.
        overage_cost:
          type: number
          nullable: true
          description: Estimated cost of overage credits. Null unless `is_metered` is true.
    UsageWindowTotals:
      type: object
      description: Consumption over exactly the requested `from`→`to` window.
      required:
        - documents
        - pages
        - credits
      properties:
        documents:
          type: integer
          description: Documents processed in the window.
        pages:
          type: integer
          description: Pages processed in the window.
        credits:
          type: number
          description: Credits consumed in the window.
    UsagePeriodBucket:
      type: object
      description: One `group_by` bucket of the usage timeline.
      required:
        - period
        - documents
        - pages
        - credits
      properties:
        period:
          type: string
          format: date-time
          description: Bucket start (UTC).
        documents:
          type: integer
          description: Documents processed in the bucket.
        pages:
          type: integer
          description: Pages processed in the bucket.
        credits:
          type: number
          description: Credits consumed in the bucket.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      x-fern-header:
        name: apiKey
        env: PULSE_API_KEY

````