Get monthly charges breakdown

GET 
/charges_breakdown

Retrieve a detailed breakdown of monthly charges for phone numbers in a specified date range. The date range cannot exceed 31 days.

Query Parameters

start_date daterequired

Start date for the charges breakdown in ISO date format (YYYY-MM-DD)

end_date date

End date for the charges breakdown in ISO date format (YYYY-MM-DD). If not provided, defaults to start_date + 1 month. The date is exclusive, data for the end_date itself is not included in the report. The interval between start_date and end_date cannot exceed 31 days.

format string

Possible values: [json, csv]

Default value: json

Response format

200: Monthly charges breakdown

application/json

• Schema
• Example (from schema)

Schema

data

object

required

user_id stringrequired

User identifier

start_date daterequired

Start date of the breakdown period

end_date daterequired

End date of the breakdown period

user_email emailrequired

User email address

currency stringrequired

Currency code

results

object[]

required

List of phone number charge breakdowns

Array [

tn stringrequired

Phone number

charge_type stringrequired

Type of charge for the number

service_owner_user_id stringrequired

User ID of the service owner

service_owner_email emailrequired

Email address of the service owner

services

object[]

required

List of services associated with this number

Array [

cost_type stringrequired

Type of cost (MRC or OTC)

name stringrequired

Service name

cost stringrequired

Cost per unit as decimal string

]

List of services associated with this number

]

List of phone number charge breakdowns

{
  "data": {
    "user_id": "0db0b4aa-a83d-4d4f-ad9b-3ba7c1ac2ce8",
    "start_date": "2025-05-01",
    "end_date": "2025-06-01",
    "user_email": "user@example.com",
    "currency": "USD",
    "results": [
      {
        "tn": "+15551234567",
        "charge_type": "local",
        "service_owner_user_id": "0db0b4aa-a83d-4d4f-ad9b-3ba7c1ac2ce8",
        "service_owner_email": "user@example.com",
        "services": [
          {
            "cost_type": "MRC",
            "name": "Local DIDs",
            "cost": "1.50"
          }
        ]
      }
    ]
  }
}

text/csv

• Schema

Schema

string

400: Bad request - invalid date range or parameters

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/charges_breakdown' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

• 200
• 400
• default

---

{
  "data": {
    "user_id": "0db0b4aa-a83d-4d4f-ad9b-3ba7c1ac2ce8",
    "start_date": "2025-05-01",
    "end_date": "2025-06-01",
    "user_email": "user@example.com",
    "currency": "USD",
    "results": [
      {
        "tn": "+15551234567",
        "charge_type": "local",
        "service_owner_user_id": "0db0b4aa-a83d-4d4f-ad9b-3ba7c1ac2ce8",
        "service_owner_email": "user@example.com",
        "services": [
          {
            "cost_type": "MRC",
            "name": "Local DIDs",
            "cost": "1.50"
          }
        ]
      }
    ]
  }
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}