> Revox API docs for developers and AI agents. Index: https://www.getrevox.com/docs/api/llms.txt · Everything in one file: https://www.getrevox.com/docs/api/llms-full.txt · OpenAPI 3.1: https://www.getrevox.com/openapi.json · MCP server: https://www.getrevox.com/api/mcp-servers/generic/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# The Usage object

```json
{
  "period": {
    "from": "from",
    "to": "to",
    "granularity": "hour",
    "timezone": "Europe/Paris"
  },
  "previous_period": { "from": "from", "to": "to" },
  "totals": {
    "credits_used": 1,
    "amount_cents": 1,
    "calls": 1,
    "connected_calls": 1,
    "talk_seconds": 98,
    "credits_by_kind": {
      "reached": 1,
      "not_reached": 1,
      "inbound": 1,
      "per_minute": 1
    },
    "credits_added": 1
  },
  "previous_totals": {
    "credits_used": 1,
    "amount_cents": 1,
    "calls": 1,
    "connected_calls": 1,
    "talk_seconds": 98,
    "credits_by_kind": {
      "reached": 1,
      "not_reached": 1,
      "inbound": 1,
      "per_minute": 1
    },
    "credits_added": 1
  },
  "series": [
    {
      "credits_used": 1,
      "amount_cents": 1,
      "calls": 1,
      "connected_calls": 1,
      "talk_seconds": 98,
      "credits_by_kind": {
        "reached": 1,
        "not_reached": 1,
        "inbound": 1,
        "per_minute": 1
      },
      "start": "start"
    }
  ],
  "by_assistant": [
    {
      "assistant_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
      "name": "Appointment reminder",
      "credits_used": 1,
      "amount_cents": 1,
      "calls": 1,
      "connected_calls": 1,
      "talk_seconds": 98
    }
  ],
  "by_campaign": [
    {
      "campaign_id": "9b2d7e41-6c3f-4a8e-b5d0-2f7a1c9e4b63",
      "name": "Appointment reminder",
      "credits_used": 1,
      "amount_cents": 1,
      "calls": 1,
      "connected_calls": 1,
      "talk_seconds": 98
    }
  ],
  "balance": {
    "credits": 1,
    "plan": "starter",
    "plan_monthly_credits": 1,
    "next_expiry": {
      "credits": 1,
      "expires_at": "2026-11-05T09:00:00Z"
    },
    "daily_average_credits": 1,
    "depletion_date": "2026-11-02"
  }
}
```

## Fields

- `period` (object)
  - `period.from` (string): Start of the period, ISO 8601.
  - `period.to` (string): End of the period (excluded), ISO 8601.
  - `period.granularity` ("hour" | "day" | "week" | "month"): The size of each point.
  - `period.timezone` (string): The timezone the points are cut in.
- `previous_period` (object): The period of the same length just before, to compare against.
  - `previous_period.from` (string): ISO 8601.
  - `previous_period.to` (string): ISO 8601, the start of `period`.
- `totals` (object): Totals over the period.
  - `totals.credits_used` (number): Credits charged (1 credit = 1 worked contact = €0.50 excl. VAT). A contact's credit is dated by its last call. Fractional only for per-minute charges from before flat pricing.
  - `totals.amount_cents` (integer): What those credits cost, in euro cents excluding VAT.
  - `totals.calls` (integer): Phone calls placed or answered: every dial counts, retries included. Browser test calls are free and not counted.
  - `totals.connected_calls` (integer): Calls answered by someone: a person or a phone menu on an outbound call, or any inbound call. A voicemail does not count.
  - `totals.talk_seconds` (integer): Time on the line, from pickup to hang-up, summed over every answered call (voicemails included).
  - `totals.credits_by_kind` (object): Credits used, split by what they paid for.
    - `totals.credits_by_kind.reached` (number): An outbound contact someone picked up (a person or a phone menu), or who called back.
    - `totals.credits_by_kind.not_reached` (number): An outbound contact billed without anyone picking up: every attempt it was allowed went unanswered or reached a voicemail.
    - `totals.credits_by_kind.inbound` (number): An inbound call your assistant answered.
    - `totals.credits_by_kind.per_minute` (number): A charge by the minute, under the pricing in place before flat per-contact credits.
  - `totals.credits_added` (integer): Credits added to the balance over the period: plan invoices, top-ups and admin grants.
- `previous_totals` (object): Totals over the previous period.
  - `previous_totals.credits_used` (number): Credits charged (1 credit = 1 worked contact = €0.50 excl. VAT). A contact's credit is dated by its last call. Fractional only for per-minute charges from before flat pricing.
  - `previous_totals.amount_cents` (integer): What those credits cost, in euro cents excluding VAT.
  - `previous_totals.calls` (integer): Phone calls placed or answered: every dial counts, retries included. Browser test calls are free and not counted.
  - `previous_totals.connected_calls` (integer): Calls answered by someone: a person or a phone menu on an outbound call, or any inbound call. A voicemail does not count.
  - `previous_totals.talk_seconds` (integer): Time on the line, from pickup to hang-up, summed over every answered call (voicemails included).
  - `previous_totals.credits_by_kind` (object): Credits used, split by what they paid for.
    - `previous_totals.credits_by_kind.reached` (number): An outbound contact someone picked up (a person or a phone menu), or who called back.
    - `previous_totals.credits_by_kind.not_reached` (number): An outbound contact billed without anyone picking up: every attempt it was allowed went unanswered or reached a voicemail.
    - `previous_totals.credits_by_kind.inbound` (number): An inbound call your assistant answered.
    - `previous_totals.credits_by_kind.per_minute` (number): A charge by the minute, under the pricing in place before flat per-contact credits.
  - `previous_totals.credits_added` (integer): Credits added to the balance over the period: plan invoices, top-ups and admin grants.
- `series` (array of object): The period point by point, oldest first, empty points included.
  - `series.credits_used` (number): Credits charged (1 credit = 1 worked contact = €0.50 excl. VAT). A contact's credit is dated by its last call. Fractional only for per-minute charges from before flat pricing.
  - `series.amount_cents` (integer): What those credits cost, in euro cents excluding VAT.
  - `series.calls` (integer): Phone calls placed or answered: every dial counts, retries included. Browser test calls are free and not counted.
  - `series.connected_calls` (integer): Calls answered by someone: a person or a phone menu on an outbound call, or any inbound call. A voicemail does not count.
  - `series.talk_seconds` (integer): Time on the line, from pickup to hang-up, summed over every answered call (voicemails included).
  - `series.credits_by_kind` (object): Credits used, split by what they paid for.
    - `series.credits_by_kind.reached` (number): An outbound contact someone picked up (a person or a phone menu), or who called back.
    - `series.credits_by_kind.not_reached` (number): An outbound contact billed without anyone picking up: every attempt it was allowed went unanswered or reached a voicemail.
    - `series.credits_by_kind.inbound` (number): An inbound call your assistant answered.
    - `series.credits_by_kind.per_minute` (number): A charge by the minute, under the pricing in place before flat per-contact credits.
  - `series.start` (string): Start of the point, ISO 8601 in UTC. Points are cut on the local calendar of `timezone`: a day point starts at local midnight.
- `by_assistant` (array of object): The period per assistant, most credits first.
  - `by_assistant.assistant_id` (string | null): The assistant. Null for calls whose assistant was deleted.
  - `by_assistant.name` (string | null): The assistant's name.
  - `by_assistant.credits_used` (number): Credits charged (1 credit = 1 worked contact = €0.50 excl. VAT). A contact's credit is dated by its last call. Fractional only for per-minute charges from before flat pricing.
  - `by_assistant.amount_cents` (integer): What those credits cost, in euro cents excluding VAT.
  - `by_assistant.calls` (integer): Phone calls placed or answered: every dial counts, retries included. Browser test calls are free and not counted.
  - `by_assistant.connected_calls` (integer): Calls answered by someone: a person or a phone menu on an outbound call, or any inbound call. A voicemail does not count.
  - `by_assistant.talk_seconds` (integer): Time on the line, from pickup to hang-up, summed over every answered call (voicemails included).
- `by_campaign` (array of object): The period per campaign, most credits first.
  - `by_campaign.campaign_id` (string | null): The campaign. Null for calls made outside any campaign (API, dashboard, inbound) or in a deleted one.
  - `by_campaign.name` (string | null): The campaign's name.
  - `by_campaign.credits_used` (number): Credits charged (1 credit = 1 worked contact = €0.50 excl. VAT). A contact's credit is dated by its last call. Fractional only for per-minute charges from before flat pricing.
  - `by_campaign.amount_cents` (integer): What those credits cost, in euro cents excluding VAT.
  - `by_campaign.calls` (integer): Phone calls placed or answered: every dial counts, retries included. Browser test calls are free and not counted.
  - `by_campaign.connected_calls` (integer): Calls answered by someone: a person or a phone menu on an outbound call, or any inbound call. A voicemail does not count.
  - `by_campaign.talk_seconds` (integer): Time on the line, from pickup to hang-up, summed over every answered call (voicemails included).
- `balance` (object): The balance now and how long it lasts at the recent pace. Does not depend on the period.
  - `balance.credits` (integer): Credits left now, whatever the period asked: each one pays for one contact.
  - `balance.plan` ("starter" | "business" | null): The organization's subscription plan; null when it has none.
  - `balance.plan_monthly_credits` (integer | null): Credits the plan adds every month; null without a plan.
  - `balance.next_expiry` (object | null): The plan credits that expire next if they are not used in time. Null when none are due to expire.
    - `balance.next_expiry.credits` (integer): Unused plan credits set to expire.
    - `balance.next_expiry.expires_at` (string): When they expire, ISO 8601.
  - `balance.daily_average_credits` (number): Credits used per day on average over the last 14 days.
  - `balance.depletion_date` (string | null): When the balance runs out at that daily average, ISO 8601. Null when nothing was used over the last 14 days.

## Returned by

- [Get credit and call usage](https://www.getrevox.com/docs/api/usage/get-credit-and-call-usage.md): `GET /usage`