Telnyx Telco Data Usage Reports API

Number lookup usage reports

GitHub OpenAPI

Operations 8

GET /legacy/reporting/usage_reports/number_lookup List telco data usage reports #
POST /legacy/reporting/usage_reports/number_lookup Submit telco data usage report #
DELETE /legacy/reporting/usage_reports/number_lookup/{id} Delete telco data usage report #
GET /legacy/reporting/usage_reports/number_lookup/{id} Get telco data usage report by ID #
GET /legacy_reporting/usage_reports/number_lookup List telco data usage reports #
POST /legacy_reporting/usage_reports/number_lookup Submit telco data usage report #
DELETE /legacy_reporting/usage_reports/number_lookup/{id} Delete telco data usage report #
GET /legacy_reporting/usage_reports/number_lookup/{id} Get telco data usage report by ID #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/telnyx:telnyx-telco-data-usage-reports-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

telnyx-telco-data-usage-reports-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Telnyx Telco Data Usage Reports API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Telco Data Usage Reports across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Telco Data Usage Reports
  description: Number lookup usage reports
paths:
  /legacy/reporting/usage_reports/number_lookup:
    get:
      tags:
      - Telco Data Usage Reports
      summary: List telco data usage reports
      description: Retrieve a paginated list of telco data usage reports
      operationId: getTelcoDataUsageReports
      parameters:
      - name: page
        in: query
        description: Page number to retrieve (1-based).
        schema:
          type: integer
          format: int32
      - name: per_page
        in: query
        description: Filter results by per page.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successfully retrieved telco data usage reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standard_TelcoDataGetUsageReportsResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      x-latency-category: responsive
    post:
      tags:
      - Telco Data Usage Reports
      summary: Submit telco data usage report
      description: Submits a new telco data (number lookup) usage report request. The report is generated asynchronously; retrieve it by its identifier once ready.
      operationId: submitTelcoDataUsageReport
      requestBody:
        description: Telco data usage request data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelcoDataUsageRequest'
        required: true
      responses:
        '200':
          description: Successfully submitted telco data usage report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelcoDataPostUsageReportResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
      x-latency-category: responsive
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /legacy/reporting/usage_reports/number_lookup/{id}:
    delete:
      tags:
      - Telco Data Usage Reports
      summary: Delete telco data usage report
      description: Delete a specific telco data usage report by its ID
      operationId: deleteTelcoDataUsageReport
      parameters:
      - name: id
        in: path
        description: Unique identifier of the resource.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted telco data usage report
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Report not found
        '500':
          description: Internal server error
      x-latency-category: responsive
    get:
      tags:
      - Telco Data Usage Reports
      summary: Get telco data usage report by ID
      description: Retrieve a specific telco data usage report by its ID
      operationId: getTelcoDataUsageReport
      parameters:
      - name: id
        in: path
        description: Unique identifier of the resource.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved telco data usage report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelcoDataGetUsageReportByIdResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Report not found
        '500':
          description: Internal server error
      x-latency-category: responsive
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /legacy_reporting/usage_reports/number_lookup:
    get:
      tags:
      - Telco Data Usage Reports
      summary: List telco data usage reports
      description: Retrieve a paginated list of telco data usage reports
      operationId: getTelcoDataUsageReports_2
      parameters:
      - name: page
        in: query
        description: Page number to retrieve (1-based).
        schema:
          type: integer
          format: int32
      - name: per_page
        in: query
        description: Filter results by per page.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successfully retrieved telco data usage reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelcoDataGetUsageReportsResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      x-latency-category: responsive
    post:
      tags:
      - Telco Data Usage Reports
      summary: Submit telco data usage report
      description: Submits a new telco data (number lookup) usage report request. The report is generated asynchronously; retrieve it by its identifier once ready.
      operationId: submitTelcoDataUsageReport_2
      requestBody:
        description: Telco data usage request data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelcoDataUsageRequest'
        required: true
      responses:
        '200':
          description: Successfully submitted telco data usage report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelcoDataPostUsageReportResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
      x-latency-category: responsive
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /legacy_reporting/usage_reports/number_lookup/{id}:
    delete:
      tags:
      - Telco Data Usage Reports
      summary: Delete telco data usage report
      description: Delete a specific telco data usage report by its ID
      operationId: deleteTelcoDataUsageReport_2
      parameters:
      - name: id
        in: path
        description: Unique identifier of the resource.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted telco data usage report
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Report not found
        '500':
          description: Internal server error
      x-latency-category: responsive
    get:
      tags:
      - Telco Data Usage Reports
      summary: Get telco data usage report by ID
      description: Retrieve a specific telco data usage report by its ID
      operationId: getTelcoDataUsageReport_2
      parameters:
      - name: id
        in: path
        description: Unique identifier of the resource.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved telco data usage report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelcoDataGetUsageReportByIdResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Report not found
        '500':
          description: Internal server error
      x-latency-category: responsive
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    standard_PaginationMeta:
      type: object
      properties:
        total_pages:
          type: integer
          format: int32
          example: 3
        total_results:
          type: integer
          format: int32
          example: 55
        page_number:
          type: integer
          format: int32
          example: 2
        page_size:
          type: integer
          format: int32
          example: 25
    TelcoDataUsageRecord:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: User ID
          example: d37bdd47-f301-42ec-b2ad-5a0465bfb632
        aggregations:
          type: array
          description: List of aggregations by lookup type
          items:
            $ref: '#/components/schemas/TelcoDataAggregation'
        record_type:
          type: string
          description: Record type identifier
          example: TelcoDataUsageRecord
    TelcoDataGetUsageReportByIdResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TelcoDataUsageReportResponse'
    TelcoDataAggregation:
      type: object
      properties:
        type:
          type: string
          description: Type of telco data lookup
          example: CNAM
        total_dips:
          type: integer
          description: Total number of lookups performed
          example: 3
        total_cost:
          type: number
          description: Total cost for this aggregation
          example: 0.009
        currency:
          type: string
          description: Currency code
          example: USD
    standard_PaginationMeta_ffba4faa88:
      type: object
      properties:
        total_pages:
          type: integer
          format: int32
          example: 3
        total_results:
          type: integer
          format: int32
          example: 55
        page_number:
          type: integer
          format: int32
          example: 2
        page_size:
          type: integer
          format: int32
          example: 25
    TelcoDataUsageReportResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the report
          example: 9783f4d7-0bfc-427a-9d6b-bc659ad16e5b
        start_date:
          type: string
          format: date
          description: Start date of the report period
          example: '2025-11-01'
        end_date:
          type: string
          format: date
          description: End date of the report period
          example: '2025-12-01'
        aggregation_type:
          type: string
          description: Type of aggregation used in the report
          example: ALL
        status:
          type: string
          description: Current status of the report
          example: COMPLETE
        report_url:
          type: string
          description: URL to download the complete report
          example: https://portal-cdrs-usage.s3.amazonaws.com/telco_data_usage_report_2025-12-02.csv
        created_at:
          type: string
          format: date-time
          description: Timestamp when the report was created
          example: '2025-12-02T20:20:57.196925Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the report was last updated
          example: '2025-12-02T20:21:08.237091Z'
        managed_accounts:
          type: array
          description: List of managed account IDs included in the report
          items:
            type: string
          example: []
        result:
          type: array
          description: Array of usage records
          items:
            $ref: '#/components/schemas/TelcoDataUsageRecord'
        record_type:
          type: string
          description: Record type identifier
          example: TelcoDataUsageReport
      description: Telco data usage report response
    TelcoDataUsageRequest:
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: Start date for the usage report
          example: '2025-02-10'
        endDate:
          type: string
          format: date
          description: End date for the usage report
          example: '2025-02-10'
        aggregationType:
          type: string
          description: Type of aggregation for the report
          enum:
          - ALL
          - BY_ORGANIZATION_MEMBER
          example: ALL
        managedAccounts:
          type: array
          description: List of managed accounts to include in the report
          items:
            type: string
          example:
          - f47ac10b-58cc-4372-a567-0e02b2c3d479
          - 6ba7b810-9dad-11d1-80b4-00c04fd430c8
    standard_TelcoDataGetUsageReportsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TelcoDataUsageReportResponse'
        meta:
          $ref: '#/components/schemas/standard_PaginationMeta_ffba4faa88'
    TelcoDataGetUsageReportsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TelcoDataUsageReportResponse'
        meta:
          $ref: '#/components/schemas/standard_PaginationMeta'
    TelcoDataPostUsageReportResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TelcoDataUsageReportResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt