---
title: "Get list of number charges"
method: GET
path: "/api/v4/billing/number_charges"
tags: ["Billing"]
---

# Get list of number charges

`GET /api/v4/billing/number_charges`

## Request

- Base URL: `https://{cluster_id}.voiso.com`
- URL: `https://{cluster_id}.voiso.com/api/v4/billing/number_charges`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/voiso/apis/voiso-api/docs/api/v4/billing/number_charges/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a paginated list of the charges for the phone numbers of the contact center, one transaction per number charge, including the charges of deleted numbers. Transactions are sorted by `created_at`, newest first. Without `created_at`, returns the transactions of the current calendar month, in UTC, up to the time of the request. Requires the `billing.numbers.read` scope.

## Query parameters

- `created_at` union
  - string, date-time
  - RangeFilterDateTime: Date-time range filter with comparison operators.
    - `eq` string, date-time
    - `gt` string, date-time
    - `gte` string, date-time
    - `lt` string, date-time
    - `lte` string, date-time
- `number` string
- `transaction_type` 'number_activation' | 'number_fee' | 'partial_number_fee' | 'number_deposit_fee' | 'number_early_termination': Type of the transaction: `number_activation` is the one-time fee for a bought number, `number_fee` the fee for a full month, `partial_number_fee` the fee for the rest of the month in which the number was bought, `number_deposit_fee` the one-time deposit for a number bought from Voiso, equal to its monthly fee, `number_early_termination` the fee for releasing a number before the end of its minimum term.
- `country` string
- `limit` integer
- `offset` integer

## Response `200`

OK

- object
  - `number_charges` BillingNumberCharge[]
    - `id` string, uuid: Transaction ID.
    - `number` string: Phone number.
    - `number_type` 'mobile' | 'national' | 'toll_free' | 'shared_cost' | 'geographic', nullable: Type of the number. Null for charges made before the type was recorded.
    - `country` string: Country of the number (ISO 3166-1 alpha-2).
    - `transaction_type` 'number_activation' | 'number_fee' | 'partial_number_fee' | 'number_deposit_fee' | 'number_early_termination': Type of the transaction: `number_activation` is the one-time fee for a bought number, `number_fee` the fee for a full month, `partial_number_fee` the fee for the rest of the month in which the number was bought, `number_deposit_fee` the one-time deposit for a number bought from Voiso, equal to its monthly fee, `number_early_termination` the fee for releasing a number before the end of its minimum term.
    - `amount` string: Charged amount, with 5 decimal places.
    - `billed_month` string: Month that the charge pays for (YYYY-MM). For `number_deposit_fee`, the month the number was bought.
    - `created_at` string, date-time: Date and time of the transaction, in UTC.
  - `metadata` Metadata: Pagination metadata for list responses.
    - `total` integer: The total number of items available for the requested resource.
    - `next_cursor` string, nullable: Cursor for fetching the next page of results when cursor-based pagination is supported.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too many requests
- `502`: Bad Gateway. The analytics service returned an error. Try again later, or narrow `created_at`.
- `504`: Gateway Timeout. The analytics service did not answer in time (15 seconds to connect and 15 seconds between reads), or could not be reached. Try again later, or narrow `created_at`.

## Changes

- **2026-11-03** `5a6ea146bd21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voiso/apis/voiso-api/changes/api/v4/billing/number_charges/get.md)

---

[API](https://skmtc.dev/voiso/apis/voiso-api.md) - [All operations](https://skmtc.dev/voiso/apis/voiso-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voiso/apis/voiso-api/revisions/5a6ea146bd21?raw)