---
title: "Get usage timeseries for a tenant"
method: GET
path: "/tenants/{tenantId}/usage/timeseries"
tags: ["Usage"]
---

# Get usage timeseries for a tenant

`GET /tenants/{tenantId}/usage/timeseries`

## Request

- Base URL: `https://api.arkhq.io/v1`
- URL: `https://api.arkhq.io/v1/tenants/{tenantId}/usage/timeseries`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/arkhq-io/apis/ark-email-api/docs/tenants/:tenantId/usage/timeseries/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns time-bucketed email statistics for a specific tenant.

**Use cases:**
- Build usage charts and graphs
- Identify sending patterns
- Detect anomalies in delivery rates

**Granularity options:**
- `hour` - Hourly buckets (best for last 7 days)
- `day` - Daily buckets (best for last 30-90 days)
- `week` - Weekly buckets (best for last 6 months)
- `month` - Monthly buckets (best for year-over-year)

The response includes a data point for each time bucket with all email metrics.

## Path parameters

- `tenantId` string, required

## Query parameters

- `period` string
- `granularity` 'hour' | 'day' | 'week' | 'month'
- `timezone` string

## Response `200`

Tenant usage timeseries

- TenantUsageTimeseriesResponse: Timeseries usage data for a tenant
  - `success` true, required
  - `data` TenantUsageTimeseriesData, required: Timeseries usage statistics
    - `tenant_id` string, required: Unique tenant identifier
    - `tenant_name` string, required: Tenant display name
    - `granularity` 'hour' | 'day' | 'week' | 'month', required: Time bucket granularity
    - `period` UsagePeriod, required: Time period for usage data
      - `start` string, date-time, required: Period start (inclusive)
      - `end` string, date-time, required: Period end (inclusive)
    - `data` UsageTimeseriesPoint[], required: Array of time-bucketed data points
      - `timestamp` string, date-time, required: Start of time bucket
      - `sent` integer, required: Emails sent in this bucket
      - `delivered` integer, required: Emails delivered in this bucket
      - `soft_failed` integer, required: Soft failures in this bucket
      - `hard_failed` integer, required: Hard failures in this bucket
      - `bounced` integer, required: Bounces in this bucket
      - `held` integer, required: Emails held in this bucket
  - `meta` ApiMeta, required
    - `requestId` string, required: Unique request identifier for debugging and support

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `404`: Tenant not found
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: Usage statistics temporarily unavailable

## Changes

- **2026-02-08** `37bce0c9a4d7`: 6 warning, 6 info
  - added the new `infrastructure_error` enum value to the `error/code` response property for the response status `400`
  - added the new `infrastructure_error` enum value to the `error/code` response property for the response status `401`
  - added the new `infrastructure_error` enum value to the `error/code` response property for the response status `404`
  - added the new `infrastructure_error` enum value to the `error/code` response property for the response status `429`
  - …8 more
- **2026-02-08** `4f8eeb0b9933`: 276 warning
  - added the new `already_exists` enum value to the `error/code` response property for the response status `400`
  - added the new `already_exists` enum value to the `error/code` response property for the response status `401`
  - added the new `already_exists` enum value to the `error/code` response property for the response status `404`
  - added the new `already_exists` enum value to the `error/code` response property for the response status `429`
  - …272 more
- **2026-02-08** `80a061ee3002`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/arkhq-io/apis/ark-email-api/changes/tenants/:tenantId/usage/timeseries/get.md)

---

[API](https://skmtc.dev/arkhq-io/apis/ark-email-api.md) - [All operations](https://skmtc.dev/arkhq-io/apis/ark-email-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arkhq-io/apis/ark-email-api/revisions/98a90852ffca?raw)