> 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/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# Get phone number usage

`GET https://www.getrevox.com/api/phone-numbers/usage`

How many calls each phone number of your organization placed and received, week by week over the last 12 weeks (current week included), with its latest call. Use it to spot numbers nobody uses anymore before deleting them.

## Request

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

## Body

No body: send the request without one.

## Response 200

```json
{
  "usage": [
    {
      "phone_number_id": "6f9a3c1e-2b7d-4e58-9a10-3d2c4b5e6f70",
      "phone_number": "+33612345678",
      "weeks": [
        {
          "week_start": "2026-11-02",
          "outbound_calls": 1,
          "outbound_connected_calls": 1,
          "inbound_calls": 1
        }
      ],
      "last_call_at": "2026-11-05T09:00:00Z"
    }
  ]
}
```

- `usage` (array of object): One entry per phone number of the organization.
  - `usage.phone_number_id` (string): ID of the phone number, as returned by [`GET /phone-numbers`](https://www.getrevox.com/docs/api/phone-numbers/get-phone-numbers.md).
  - `usage.phone_number` (string): The number, in E.164 format.
  - `usage.weeks` (array of object): One entry per week of the window, oldest first.
    - `usage.weeks.week_start` (string): Monday that starts the week, as YYYY-MM-DD (UTC). Every week of the window is listed, including weeks without calls.
    - `usage.weeks.outbound_calls` (integer): Calls dialed from this number that week, each retry counted on its own.
    - `usage.weeks.outbound_connected_calls` (integer): Of outbound_calls, the dials someone picked up: a person or a phone menu, not a voicemail or call screening. Divide by outbound_calls for the number's answer rate that week.
    - `usage.weeks.inbound_calls` (integer): Calls received on this number that week.
  - `usage.last_call_at` (string | null): When the latest call dialed from or received on this number started (ISO 8601). Null when it had no call during the window: a number that stays null is a candidate for deletion.