---
title: "Get usage history"
method: GET
path: "/v1/organizations/{organization_id}/usage_history"
tags: ["Organization"]
---

# Get usage history

`GET /v1/organizations/{organization_id}/usage_history`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/organizations/{organization_id}/usage_history`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Retrieves the daily history of the usage count associated with a particular service plan limit.

 Telerivet stores a snapshot of each organization's usage once per day, shortly after midnight in the organization's time zone. For usage types that are counted per day (`external_messages_day`, `api_requests_day`, `service_invocations_day`, and `ai_chat_credits_day`), each entry contains the usage counted during that entire day. For all other usage types, each entry contains the usage count at the time the snapshot was recorded.

 The maximum supported date range is 500 days between start_date and end_date. If the requested date range includes the current time, the response will also include a final entry with `current: true` containing the live usage count computed at the time of the API request.

 Usage snapshots are only recorded while an organization is active, so an entry may not be available for every date in the requested range.

## Path parameters

- `organization_id` string, required

## Query parameters

- `usage_type` 'contacts' | 'phones' | 'active_services' | 'users' | 'stored_messages' | 'service_invocations_day' | 'api_requests_day' | 'projects' | 'data_rows' | 'script_module_mb' | 'stored_file_mb' | 'custom_actions' | 'groups' | 'custom_contact_fields' | 'external_messages_day' | 'external_messages_period' | 'ai_chat_credits_day', required
- `start_date` string, required
- `end_date` string, required

## Response `200`

Successful response

- object
  - `timezone_id` string: The organization's time zone ID, used to determine the date associated with each entry
  - `usage_type` string: The usage type from the request
  - `history` object[]: List of usage entries in chronological order, one for each daily usage snapshot recorded within the requested date range (plus the live usage entry if the range includes the current time).
    - `time_counted` integer: UNIX timestamp when the usage was counted
    - `date` string: Date associated with time_counted in the organization's time zone, in YYYY-MM-DD format
    - `current` boolean: True for the final entry containing the live usage count at the time of the API request; false for entries from stored daily snapshots
    - `value` integer: Usage count that applies toward the service plan limit (the same counter returned by [getUsage](#Organization.getUsage))
    - `simulated_value` integer: Usage associated with simulated routes, which does not apply toward the service plan limit (null when not applicable to the usage type)
    - `exempt_value` integer: Usage that is exempt from the service plan limit (null when not applicable to the usage type)
    - `total_value` integer: Total usage, including `value`, `simulated_value`, and `exempt_value`
    - `limit` integer: Value of the corresponding service plan limit at the time the usage was counted (null if unlimited)

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)