---
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`

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

---

[API](https://skmtc.net/arkhq-io/apis/ark-email-api.md) · [All operations](https://skmtc.net/arkhq-io/apis/ark-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arkhq-io/ark-email-api/versions/98a90852ffca/schema)