AgentLine Billing API

openapi: 3.2.0
info:
  title: Agentline Cloud Billing API
  version: 0.3.0
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  description: 'Operations tagged Billing across 2 of this provider''s published API definitions: agentline.cloud_openapi.json, agentline-cloud-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentline.cloud
  description: Production
tags:
- name: Billing
paths:
  /v1/billing/balance:
    get:
      tags:
      - Billing
      summary: Get Balance
      description: 'Get your AI telephony account balance and rate card.


        Returns the current balance and currency. Plan allowances are used first. Calls beyond the allowance are 0.12 USD per minute in both directions. A 0-second call is free. A connected call has a one-minute minimum, then the actual duration rounded up to the cent. Additional phone numbers are 3.00 USD per month. The rate card also includes SMS, sent or received.

        Use this to check affordability before paid telephony operations.'
      operationId: get_account_balance
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
      x-fern-sdk-group-name:
      - billing
      x-fern-sdk-method-name: get_balance
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/billing/expenditure:
    get:
      tags:
      - Billing
      summary: Get Expenditure
      description: 'Get a detailed expenditure breakdown for AI telephony usage.


        Shows total spend split by category (voice calls, phone number

        provisioning, top-ups, refunds) with counts and averages.

        Useful for tracking how much your AI agents are spending on

        phone calls and phone numbers.'
      operationId: get_expenditure_breakdown
      security:
      - API Key or OAuth: []
      parameters:
      - name: period
        in: query
        required: false
        schema:
          type: string
          description: 'Time period: ''current_month'', ''last_month'', ''all_time'', or ''YYYY-MM'''
          default: current_month
          title: Period
        description: 'Time period: ''current_month'', ''last_month'', ''all_time'', or ''YYYY-MM'''
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - billing
      x-fern-sdk-method-name: get_expenditure
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/billing/expenditure/calls:
    get:
      tags:
      - Billing
      summary: Get Call Expenditure
      description: 'List individual call charges from AI agent phone calls.


        Each entry includes the voice call duration, cost, direction

        (inbound/outbound), phone numbers involved, and timestamp.

        Shows exactly how much each AI agent call cost.'
      operationId: get_call_charges
      security:
      - API Key or OAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of call charges to return (1-200)
          default: 50
          title: Limit
        description: Maximum number of call charges to return (1-200)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip for pagination
          default: 0
          title: Offset
        description: Number of records to skip for pagination
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - billing
      x-fern-sdk-method-name: list_call_charges
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/billing/expenditure/numbers:
    get:
      tags:
      - Billing
      summary: Get Number Expenditure
      description: 'List phone number provisioning charges.


        Shows the cost of each phone number bought for your AI agents,

        including the number, country, and current status.'
      operationId: get_number_charges
      security:
      - API Key or OAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of number charges to return (1-200)
          default: 50
          title: Limit
        description: Maximum number of number charges to return (1-200)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip for pagination
          default: 0
          title: Offset
        description: Number of records to skip for pagination
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - billing
      x-fern-sdk-method-name: list_number_charges
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/billing/summary:
    get:
      tags:
      - Billing
      summary: Get Spending Summary
      description: 'Month-over-month spending summary.


        Returns total debits grouped by month for trend analysis.'
      operationId: get_spending_summary
      security:
      - API Key or OAuth: []
      parameters:
      - name: months
        in: query
        required: false
        schema:
          type: integer
          maximum: 24
          minimum: 1
          description: Number of months to show
          default: 6
          title: Months
        description: Number of months to show
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - billing
      x-fern-sdk-method-name: get_summary
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/billing/verify/{call_id}:
    get:
      tags:
      - Billing
      summary: Verify Call Deduction
      description: 'Verify that the balance was correctly reduced after a specific call.


        Returns the call details, the expected charge based on duration,

        the actual ledger entry, and a boolean `deducted` flag indicating

        whether the charge was applied correctly.


        Use this after a call completes to confirm billing accuracy.'
      operationId: verify_call_billing
      security:
      - API Key or OAuth: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.agentline.cloud
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    API_Key_or_OAuth:
      type: http
      description: 'AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).'
      scheme: bearer
      bearerFormat: API key (al_live_...)
      x-fern-bearer:
        name: apiKey
        env: AGENTLINE_API_KEY
x-refined-from:
- agentline.cloud_openapi.json
- agentline-cloud-openapi.json