> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Telnyx product usage data (BETA) > Get Telnyx usage data by product, broken out by the specified dimensions ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/account-billing/usage-reports.yml get /usage_reports openapi: 3.1.0 info: title: Telnyx Usage Reports API version: 2.0.0 description: API for Usage reports. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] paths: /usage_reports: get: tags: - Usage Reports (BETA) summary: Get Telnyx product usage data (BETA) description: Get Telnyx usage data by product, broken out by the specified dimensions operationId: GetUsageReports parameters: - name: product in: query description: Telnyx product required: true schema: type: string examples: product=wireless: value: wireless summary: wireless product=messaging: value: messaging summary: messaging - name: dimensions in: query description: Breakout by specified product dimensions required: true schema: type: array items: type: string examples: dimensions=direction,currency,message_type: value: - direction - currency - message_type summary: Dimensions aggregation list - name: metrics in: query description: Specified product usage values required: true schema: type: array items: type: string examples: metrics=cost,billed_sec: value: - cost - billed_sec summary: Metrics aggregation list - name: start_date in: query description: >- The start date for the time range you are interested in. The maximum time range is 31 days. Format: YYYY-MM-DDTHH:mm:ssZ required: false schema: type: string examples: start_date=2024-02-01T00:00:00Z: value: '2024-02-01T00:00:00Z' summary: >- Aggregate for records with timestamp starting at specified date and time. - name: end_date in: query description: >- The end date for the time range you are interested in. The maximum time range is 31 days. Format: YYYY-MM-DDTHH:mm:ssZ required: false schema: type: string examples: end_date=2024-03-01T00:00:00Z: value: '2024-03-01T00:00:00Z' summary: >- Aggregate for records with timestamp ending at specified date and time. - name: date_range in: query description: >- A more user-friendly way to specify the timespan you want to filter by. More options can be found in the Telnyx API Reference docs. required: false schema: type: string examples: date_range=today: value: today summary: >- today - Searches for records with timestamp starting at `00:00:00` of the current day date_range=last_3_days: value: last_3_days summary: >- last_3_days - Searches for records with timestamp starting at `00:00:00` since 3 days ago - name: filter in: query description: Filter records on dimensions required: false schema: type: string examples: filter[currency]=USD: value: filter[currency]=USD summary: Filter currency on USD filter[direction]=inbound: value: filter[direction]=inbound summary: Filter direction on Inbound filter[country_code]=NLD: value: filter[country_code]=NLD summary: Filter country code on NLD - name: managed_accounts in: query description: >- Return the aggregations for all Managed Accounts under the user making the request. required: false schema: type: boolean examples: managed_accounts=true: value: false summary: Fetch aggregations for all Managed Accounts - name: sort description: Specifies the sort order for results in: query required: false schema: type: array items: type: string examples: sort=created_at: value: - created_at summary: >- Sorts search results using the `created_at` date-time in ascending order sort=-created_at: value: - '-created_at' summary: >- Sorts search results using the `-created_at` date-time in descending order - name: format in: query description: >- Specify the response format (csv or json). JSON is returned by default, even if not specified. required: false schema: type: string enum: - csv - json examples: format=json: value: json summary: Get the response in JSON format format=csv: value: csv summary: Get the response in CSV format - name: authorization_bearer in: header schema: type: string description: Authenticates the request with your Telnyx API V2 KEY - name: page in: query style: deepObject explode: true description: >- Consolidated page parameter (deepObject style). Originally: page[number], page[size] schema: type: object properties: number: title: Page[Number] minimum: 1 type: integer default: 1 size: title: Page[Size] maximum: 5000 type: integer default: 20 examples: page[number]=1&page[size]=20: value: number: 1 size: 20 summary: >- Returns the first page with 20 records per page (default pagination) page[number]=2&page[size]=20: value: number: 2 size: 20 summary: Returns the second page with 20 records per page page[number]=1&page[size]=50: value: number: 1 size: 50 summary: >- Returns the first page with 50 records per page (larger page size) page[number]=5&page[size]=100: value: number: 5 size: 100 summary: Returns the fifth page with 100 records per page responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/UsageReportsResponse' text/csv: schema: type: string description: CSV formatted data example: >- user_id,direction,product,cost,billed_sec 3ca7bd3d-7d82-4e07-9df4-009123068320,inbound,forking,0.000800,17.000000 ... '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/usage-reports_ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/usage-reports_ErrorResponse' security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: >- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const usageReportListResponse of client.usageReports.list({ dimensions: ['string'], metrics: ['string'], product: 'product', })) { console.log(usageReportListResponse); } - lang: Python source: |- import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) page = client.usage_reports.list( dimensions=["string"], metrics=["string"], product="product", ) page = page.data[0] print(page) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.UsageReports.List(context.TODO(), telnyx.UsageReportListParams{\n\t\tDimensions: []string{\"string\"},\n\t\tMetrics: []string{\"string\"},\n\t\tProduct: \"product\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.usagereports.UsageReportListPage; import com.telnyx.sdk.models.usagereports.UsageReportListParams; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); UsageReportListParams params = UsageReportListParams.builder() .addDimension("string") .addMetric("string") .product("product") .build(); UsageReportListPage page = client.usageReports().list(params); } } - lang: Ruby source: >- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") page = telnyx.usage_reports.list(dimensions: ["string"], metrics: ["string"], product: "product") puts(page) - lang: CLI source: |- telnyx usage-reports list \ --api-key 'My API Key' \ --dimension string \ --metric string \ --product product components: schemas: UsageReportsResponse: type: object properties: meta: $ref: '#/components/schemas/PaginationData' data: type: array example: - product: messaging cost: 0.012 parts: 12 count: 8 customer_carrier_fee: 0 product_name: long_code country_iso: LC direction: outbound - product: messaging cost: 0.021 parts: 21 count: 12 customer_carrier_fee: 0 product_name: long_code country_iso: MP direction: outbound items: type: object additionalProperties: true usage-reports_ErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorRecord' PaginationData: type: object properties: total_pages: type: integer description: Total number of pages. example: 5 total_results: type: integer description: Total number of results. example: 100 page_number: type: integer description: Selected page number. example: 1 page_size: type: integer description: Records per single page example: 20 ErrorRecord: type: object properties: code: type: string description: >- an application-specific error code, expressed as a stringified 5-digit integer example: '10003' title: type: string description: >- a short, human-readable summary of the problem, with NO punctuation, that SHOULD NOT CHANGE from occurrence to occurrence of the problem, except for purposes of localization example: Metrics invalid values detail: type: string description: >- a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized example: >- Available metrics values for sip-trunking: connected,cost,completed,call_sec,attempted,billed_sec. source: $ref: '#/components/schemas/SourceResponse' meta: $ref: '#/components/schemas/MetaResponse' SourceResponse: type: object properties: pointer: type: string description: >- A JSON Pointer [RFC6901] to the associated entity in the request document example: /title parameter: type: string description: a string indicating which URI query parameter caused the error example: metrics MetaResponse: type: object properties: url: type: string description: This should likely be a URL to the relevant documentation example: https://developers.telnyx.com/docs/overview/errors/10001 securitySchemes: bearerAuth: scheme: bearer type: http ````