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

# Get credit and call usage

`GET https://www.getrevox.com/api/usage`

Credits used, calls placed, calls answered and time on the line over a period, point by point and per assistant and campaign, compared with the period just before. Also returns the balance now and the date it runs out at the recent pace.

## Before you call

- Without parameters it returns the current month so far, in Europe/Paris, by day.
- 1 credit = 1 worked contact = €0.50 excl. VAT: a contact is charged once, however many times it is called. `credits_by_kind` says what the credits paid for.
- `balance` is the balance now, whatever the period: `depletion_date` is when it runs out at the pace of the last 14 days.

## Request

```bash
curl -X GET "https://www.getrevox.com/api/usage" \
  -H "Authorization: Bearer $REVOX_API_KEY"
```

## Query parameters

- `from` (string (date-time), optional): Start of the period, ISO 8601 (e.g. 2026-11-01T00:00:00+01:00). Default: the start of the current month in `timezone`.
- `to` (string (date-time), optional): End of the period, excluded, ISO 8601. Default: now.
- `granularity` ("hour" | "day" | "week" | "month", optional): Size of each point of `series`. Default: hour up to 2 days, day up to 92 days, week up to a year, month beyond. At most 400 points.
- `timezone` (string, optional): IANA timezone the points and the default period are cut in. Default: Europe/Paris.

## Body

No body: send the request without one.

## Response 200

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

A [Usage](https://www.getrevox.com/docs/api/objects/usage.md) object: see "Objects on this page" below.

## Errors

- `400` Invalid request: a field or parameter failed validation: `{"message":"Request validation failed","bodyErrors":{"issues":[{"path":["phone_number"],"message":"Invalid input: expected string, received undefined","code":"invalid_type"}]}}`
- `401` Missing or invalid API key: `{"error":"Unauthorized, invalid API key"}`
- Every status is explained under Errors in https://www.getrevox.com/docs/api.md#errors.

## Objects on this page

Defined on their own pages: [Usage](https://www.getrevox.com/docs/api/objects/usage.md).