---
title: "Retrieve current or historical processing usage"
method: GET
path: "/v1/usage"
---

# Retrieve current or historical processing usage

`GET /v1/usage`

## Request

- Base URL: `https://api.temlavo.com`
- URL: `https://api.temlavo.com/v1/usage`
- Auth: HTTP bearer

## Query parameters

- `accounting_entity_id` string: Opaque case-sensitive accounting entity namespace with 1..255 Unicode code points, no surrounding whitespace, and no Cc/U+2028/U+2029 control characters
- `periods_ago` string

## Response `200`

The usage report for the requested period.

- union
  - object
    - `period` object, required: The billing period reported. It is null only when there is no plan.
      - `type` 'trial', required: The kind of period.
      - `start` string, date-time, required
      - `end` string, date-time, required
    - `plan` 'trial', required: The account's plan for this period.
    - `included_pages` 100, required: Pages the plan includes in this period.
    - `used_pages` integer, required: Processed pages counted in this period.
    - `remaining_pages` integer, required: Included pages left.
    - `overage_pages` 0, required: Pages beyond the included pages, on paid plans.
    - `attribution` UsageAttribution
      - `accounting_entity_id` string, required: Opaque case-sensitive accounting entity namespace with 1..255 Unicode code points, no surrounding whitespace, and no Cc/U+2028/U+2029 control characters
      - `processed_pages` integer, required: Processed pages attributed to it in this period.
  - object
    - `period` object, required: The billing period reported. It is null only when there is no plan.
      - `type` 'subscription', required: The kind of period.
      - `start` string, date-time, required
      - `end` string, date-time, required
    - `plan` 'starter', required: The account's plan for this period.
    - `included_pages` 500, required: Pages the plan includes in this period.
    - `used_pages` integer, required: Processed pages counted in this period.
    - `remaining_pages` integer, required: Included pages left.
    - `overage_pages` integer, required: Pages beyond the included pages, on paid plans.
    - `attribution` UsageAttribution
      - `accounting_entity_id` string, required: Opaque case-sensitive accounting entity namespace with 1..255 Unicode code points, no surrounding whitespace, and no Cc/U+2028/U+2029 control characters
      - `processed_pages` integer, required: Processed pages attributed to it in this period.
  - object
    - `period` object, required: The billing period reported. It is null only when there is no plan.
      - `type` 'subscription', required: The kind of period.
      - `start` string, date-time, required
      - `end` string, date-time, required
    - `plan` 'pro', required: The account's plan for this period.
    - `included_pages` 3000, required: Pages the plan includes in this period.
    - `used_pages` integer, required: Processed pages counted in this period.
    - `remaining_pages` integer, required: Included pages left.
    - `overage_pages` integer, required: Pages beyond the included pages, on paid plans.
    - `attribution` UsageAttribution
      - `accounting_entity_id` string, required: Opaque case-sensitive accounting entity namespace with 1..255 Unicode code points, no surrounding whitespace, and no Cc/U+2028/U+2029 control characters
      - `processed_pages` integer, required: Processed pages attributed to it in this period.
  - object
    - `period` unknown, required
    - `plan` 'none', required: The account's plan for this period.
    - `included_pages` 0, required: Pages the plan includes in this period.
    - `used_pages` 0, required: Processed pages counted in this period.
    - `remaining_pages` 0, required: Included pages left.
    - `overage_pages` 0, required: Pages beyond the included pages, on paid plans.
    - `attribution` UsageAttribution
      - `accounting_entity_id` string, required: Opaque case-sensitive accounting entity namespace with 1..255 Unicode code points, no surrounding whitespace, and no Cc/U+2028/U+2029 control characters
      - `processed_pages` integer, required: Processed pages attributed to it in this period.

## Other responses

- `400`: Error: `invalid_request`
- `401`: Error: `invalid_api_key`
- `404`: Error: `usage_period_not_found`
- `429`: Error: `rate_limit_exceeded`
- `500`: Error: `internal_error`

---

[API](https://skmtc.dev/temlavo/apis/temlavo-invoice-extraction-api.md) - [All operations](https://skmtc.dev/temlavo/apis/temlavo-invoice-extraction-api/llms.txt) - [OpenAPI document](https://skmtc.dev/temlavo/apis/temlavo-invoice-extraction-api/revisions/e69b431a11d1?raw)