> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkarta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List transactions

> List your credit and debit transactions.

Filter by `request_id` or a date range. Results are returned newest first.

For the next page, increase `offset` by `limit` until you reach `pagination.total`. See the [billing guide](https://docs.getkarta.ai/guides/billing.md#find-transactions).


## OpenAPI

````yaml openapi.json GET /billing/transactions
openapi: 3.1.0
info:
  title: Karta Public API
  version: 1.0.0-draft
  description: >-
    Karta API reference for accounts, agents, calls, campaigns, WebSocket
    sessions, and billing.
servers:
  - url: https://api.getkarta.ai/public/v1
    description: Production
security:
  - BearerApiKey: []
tags:
  - name: Account
  - name: Agents
  - name: Calls
  - name: Phone numbers
  - name: Campaigns
  - name: Realtime
  - name: Billing
  - name: Webhooks
    description: Outgoing call events delivered to your server.
paths:
  /billing/transactions:
    get:
      tags:
        - Billing
      summary: List transactions
      description: List your credit and debit transactions.
      operationId: listTransactions
      parameters:
        - name: X-Request-ID
          in: header
          required: false
          description: Optional request-tracing identifier.
          schema:
            type: string
          example: example-request-001
        - name: limit
          in: query
          required: false
          description: Maximum number of items to return.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          description: Number of items to skip.
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: entry_type
          in: query
          required: false
          description: Filter by credit or debit transactions.
          schema:
            type: string
            enum:
              - credit
              - debit
        - name: request_id
          in: query
          required: false
          description: Filter by request ID; overrides the date range.
          schema:
            type: string
        - name: start_date
          in: query
          required: false
          description: Required with end_date when request_id is absent.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: >-
            End date, inclusive in the server timezone; required with start_date
            when request_id is omitted.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Successful response.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPage'
              example:
                transactions:
                  - id: '123456'
                    entry_type: debit
                    amount: 1.5
                    feature: voice
                    request_id: example-request-001
                    created_at: '2026-09-01T10:00:00.000Z'
                pagination:
                  total: 1
                  limit: 50
                  offset: 0
        '400':
          description: Invalid request or account configuration.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AuthProblem'
                    title: Authentication or account configuration error
                  - $ref: '#/components/schemas/RequestProcessingError'
                    title: Request processing error
                  - $ref: '#/components/schemas/TransactionValidationError'
                    title: Transaction query error
              examples:
                configuration:
                  summary: Account configuration error
                  value:
                    type: https://httpstatus.es/400
                    title: Missing Data Residency
                    status: 400
                    detail: Client dataResidency not set. Please contact support.
                    instance: example-request-001
                    code: missing_data_residency
                request:
                  summary: Request parsing error (illustrative message)
                  value:
                    message: Unexpected end of JSON input
                TransactionValidationError:
                  summary: Missing date range (when request_id is absent)
                  value:
                    error: MISSING_DATE_PARAMETER
                    message: start_date and end_date are required
        '401':
          description: Authentication failed.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AuthProblem'
                    title: Authentication or account configuration error
                  - $ref: '#/components/schemas/MissingAccountContextError'
                    title: Missing account context
              examples:
                authentication:
                  summary: Missing API key
                  value:
                    type: https://httpstatus.es/401
                    title: Invalid API Key
                    status: 401
                    detail: API key is required
                    instance: example-request-001
                    code: invalid_api_key
                MissingAccountContextError:
                  summary: Missing account context
                  value:
                    error: UNAUTHORIZED
        '403':
          description: API key not permitted for this operation.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProblem'
                title: Authentication or account configuration error
              examples:
                authentication:
                  summary: Wrong key type
                  value:
                    type: https://httpstatus.es/403
                    title: Wrong API Key Type
                    status: 403
                    detail: Widget API keys may only be used on /widget paths
                    instance: example-request-001
                    code: wrong_key_audience
        '500':
          description: Internal server error.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AuthProblem'
                    title: Authentication or account configuration error
                  - $ref: '#/components/schemas/RequestProcessingError'
                    title: Request processing error
                  - $ref: '#/components/schemas/LedgerLookupError'
                    title: Transaction lookup failure
              examples:
                authentication:
                  summary: Authentication failure
                  value:
                    type: https://httpstatus.es/500
                    title: Internal Server Error
                    status: 500
                    detail: Authentication failed
                    instance: example-request-001
                    code: internal_error
                request:
                  summary: Request processing failure
                  value:
                    message: Internal Server Error
                LedgerLookupError:
                  summary: Transaction lookup failure
                  value:
                    error: LEDGER_FETCH_FAILED
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            : "${KARTA_API_KEY:?Set your API key}"


            curl --fail-with-body --get
            'https://api.getkarta.ai/public/v1/billing/transactions' \
              -H "Authorization: Bearer $KARTA_API_KEY" \
              --data-urlencode 'start_date=2026-09-01' \
              --data-urlencode 'end_date=2026-09-07'
        - lang: python
          label: Python
          source: >-
            import json

            import os

            from urllib.parse import urlencode

            from urllib.request import Request, urlopen


            query = urlencode({"start_date": "2026-09-01", "end_date":
            "2026-09-07"})

            request = Request(
                f"https://api.getkarta.ai/public/v1/billing/transactions?{query}",
                headers={"Authorization": f"Bearer {os.environ['KARTA_API_KEY']}"},
            )

            with urlopen(request, timeout=30) as response:
                print(json.load(response))
        - lang: javascript
          label: JavaScript
          source: >-
            // Run on your server.

            const { KARTA_API_KEY } = process.env;

            if (!KARTA_API_KEY) throw new Error("Set your API key");

            const query = new URLSearchParams({
              start_date: "2026-09-01",
              end_date: "2026-09-07",
            });

            const response = await fetch(
              `https://api.getkarta.ai/public/v1/billing/transactions?${query}`,
              { headers: { "Authorization": `Bearer ${KARTA_API_KEY}` } }
            );

            if (!response.ok) throw new Error(`${response.status}: ${await
            response.text()}`);

            console.log(await response.json());
components:
  schemas:
    TransactionPage:
      type: object
      properties:
        transactions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: >-
                  Ledger identifier. Preserve as a string to avoid loss of
                  precision.
              entry_type:
                type: string
                enum:
                  - credit
                  - debit
              amount:
                type: number
                description: Positive credit amount; entry_type determines direction.
              feature:
                type: string
              request_id:
                type:
                  - string
                  - 'null'
                description: >-
                  Request context associated with the transaction, when
                  available.
              created_at:
                type: string
                format: date-time
        pagination:
          type: object
          properties:
            total:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
    AuthProblem:
      type: object
      properties:
        type:
          type: string
          description: Identifier for this error category.
        title:
          type: string
          description: Short summary of the error.
        status:
          type: integer
          description: HTTP status code for this response.
        detail:
          type: string
          description: Explanation of the failure.
        instance:
          type: string
          description: Request identifier.
        code:
          type: string
          description: Machine-readable error code.
      title: Authentication or account configuration error
    RequestProcessingError:
      title: Request processing error
      type: object
      properties:
        message:
          type: string
          description: Description of the request-processing failure.
        errors:
          type: array
          items:
            additionalProperties: true
            type: object
          description: Additional error details, when supplied.
    TransactionValidationError:
      title: Transaction query error
      type: object
      properties:
        error:
          type: string
          enum:
            - INVALID_PAGINATION
            - INVALID_ENTRY_TYPE
            - MISSING_DATE_PARAMETER
            - INVALID_DATE_FORMAT
            - INVALID_DATE_RANGE
            - INVALID_REQUEST
          description: Machine-readable error code.
        message:
          type: string
          description: Explanation of the failure.
    MissingAccountContextError:
      title: Missing account context
      type: object
      properties:
        error:
          type: string
          enum:
            - UNAUTHORIZED
    LedgerLookupError:
      title: Transaction lookup failure
      type: object
      properties:
        error:
          type: string
          enum:
            - LEDGER_FETCH_FAILED
          description: Machine-readable error code.
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      description: 'API key in the format: Bearer YOUR_KARTA_API_KEY.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.