Telnyx API — Usage Reports (BETA)

naftiko: 1.0.0-alpha2
info:
  label: Telnyx API — Usage Reports (BETA)
  description: 'Telnyx API — Usage Reports (BETA). 2 operations. Lead operation: Get Telnyx product usage data (BETA). Self-contained
    Naftiko capability covering one Telnyx business surface.'
  tags:
  - Telnyx
  - Usage Reports (BETA)
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TELNYX_API_KEY: TELNYX_API_KEY
capability:
  consumes:
  - type: http
    namespace: telnyx-usage-reports-beta
    baseUri: https://api.telnyx.com/v2
    description: Telnyx API — Usage Reports (BETA) business capability. Self-contained, no shared references.
    resources:
    - name: usage_reports
      path: /usage_reports
      operations:
      - name: getusagereports
        method: GET
        description: Get Telnyx product usage data (BETA)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: product
          in: query
          type: string
          description: Telnyx product
          required: true
        - name: dimensions
          in: query
          type: array
          description: Breakout by specified product dimensions
          required: true
        - name: metrics
          in: query
          type: array
          description: Specified product usage values
          required: true
        - name: start_date
          in: query
          type: string
          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'
        - name: end_date
          in: query
          type: string
          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'
        - name: date_range
          in: query
          type: string
          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.
        - name: filter
          in: query
          type: string
          description: Filter records on dimensions
        - name: managed_accounts
          in: query
          type: boolean
          description: Return the aggregations for all Managed Accounts under the user making the request.
        - name: sort
          in: query
          type: array
          description: Specifies the sort order for results
        - name: format
          in: query
          type: string
          description: Specify the response format (csv or json). JSON is returned by default, even if not specified.
        - name: authorization_bearer
          in: header
          type: string
        - name: page
          in: query
          type: object
          description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
    - name: usage_reports-options
      path: /usage_reports/options
      operations:
      - name: listusagereportsoptions
        method: GET
        description: Get Usage Reports query options (BETA)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: product
          in: query
          type: string
          description: Options (dimensions and metrics) for a given product. If none specified, all products will be returned.
        - name: authorization_bearer
          in: header
          type: string
    authentication:
      type: bearer
      token: '{{env.TELNYX_API_KEY}}'
  exposes:
  - type: rest
    namespace: telnyx-usage-reports-beta-rest
    port: 8080
    description: REST adapter for Telnyx API — Usage Reports (BETA). One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/usage-reports
      name: usage-reports
      description: REST surface for usage_reports.
      operations:
      - method: GET
        name: getusagereports
        description: Get Telnyx product usage data (BETA)
        call: telnyx-usage-reports-beta.getusagereports
        with:
          product: rest.product
          dimensions: rest.dimensions
          metrics: rest.metrics
          start_date: rest.start_date
          end_date: rest.end_date
          date_range: rest.date_range
          filter: rest.filter
          managed_accounts: rest.managed_accounts
          sort: rest.sort
          format: rest.format
          authorization_bearer: rest.authorization_bearer
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/usage-reports/options
      name: usage-reports-options
      description: REST surface for usage_reports-options.
      operations:
      - method: GET
        name: listusagereportsoptions
        description: Get Usage Reports query options (BETA)
        call: telnyx-usage-reports-beta.listusagereportsoptions
        with:
          product: rest.product
          authorization_bearer: rest.authorization_bearer
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: telnyx-usage-reports-beta-mcp
    port: 9090
    transport: http
    description: MCP adapter for Telnyx API — Usage Reports (BETA). One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: get-telnyx-product-usage-data
      description: Get Telnyx product usage data (BETA)
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-usage-reports-beta.getusagereports
      with:
        product: tools.product
        dimensions: tools.dimensions
        metrics: tools.metrics
        start_date: tools.start_date
        end_date: tools.end_date
        date_range: tools.date_range
        filter: tools.filter
        managed_accounts: tools.managed_accounts
        sort: tools.sort
        format: tools.format
        authorization_bearer: tools.authorization_bearer
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-usage-reports-query-options
      description: Get Usage Reports query options (BETA)
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: telnyx-usage-reports-beta.listusagereportsoptions
      with:
        product: tools.product
        authorization_bearer: tools.authorization_bearer
      outputParameters:
      - type: object
        mapping: $.