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

# Billing Consumption

> Aggregated negative-balance debits from your credit account, bucketed by date and
product. Useful for usage dashboards, monthly invoice reconciliation, and anomaly
detection. Required scope `billing:read`.

By default, top-ups (positive credits) are excluded — pass `include_topups=true` to
include them.


Aggregated debits from your credit account, bucketed by date and product. Useful for usage dashboards, monthly reconciliation, and anomaly detection.

By default, top-ups are excluded — pass `include_topups=true` to fold them in for full statement parity.

## Common queries

```bash theme={null}
# This month's voice-call spend, day by day
curl "https://api.goyappr.com/billing/consumption?from=2026-05-01T00:00:00Z&group_by=day&product=voice_call" \
  -H "Authorization: Bearer $YAPPR_API_KEY"

# Eval spend for the year, monthly
curl "https://api.goyappr.com/billing/consumption?from=2026-01-01T00:00:00Z&group_by=month&product=eval_run" \
  -H "Authorization: Bearer $YAPPR_API_KEY"

# Per-agent voice-call spend last 30 days
curl "https://api.goyappr.com/billing/consumption?group_by=agent&product=voice_call" \
  -H "Authorization: Bearer $YAPPR_API_KEY"

# Total spend for one specific suite_run (no native filter — query eval_runs and sum)
# (use `GET /agent-eval/runs?suite_run_id=...` and sum `total_cost_cents` client-side)
```

## Products

| Product        | What it covers                                                                   |
| -------------- | -------------------------------------------------------------------------------- |
| `voice_call`   | Paid call minutes (inbound + outbound + web). Per-agent grouping populates here. |
| `eval_run`     | Agent-eval runs.                                                                 |
| `phone_number` | Monthly number rent.                                                             |
| `topup`        | Positive credit purchases. Excluded by default.                                  |
| `refund`       | Reverse charges (negative).                                                      |


## OpenAPI

````yaml GET /billing/consumption
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /billing/consumption:
    get:
      tags:
        - Billing
      summary: Billing consumption
      description: >
        Aggregated negative-balance debits from your credit account, bucketed by
        date and

        product. Useful for usage dashboards, monthly invoice reconciliation,
        and anomaly

        detection. Required scope `billing:read`.


        By default, top-ups (positive credits) are excluded — pass
        `include_topups=true` to

        include them.
      operationId: getBillingConsumption
      parameters:
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Start of the window. Defaults to 30 days ago.
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: End of the window (exclusive). Defaults to now.
        - in: query
          name: group_by
          schema:
            type: string
            enum:
              - day
              - month
              - total
              - agent
            default: day
          description: >-
            Bucket granularity. `agent` returns one row per agent_id (currently
            only populated for `voice_call`).
        - in: query
          name: product
          schema:
            type: string
            enum:
              - voice_call
              - eval_run
              - phone_number
              - topup
              - refund
          description: Filter to a single product category.
        - in: query
          name: include_topups
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Consumption rows
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: string
                    format: date-time
                  to:
                    type: string
                    format: date-time
                  group_by:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingConsumption'
        '400':
          description: Invalid `from` / `to` range or unknown `product`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BillingConsumption:
      type: object
      description: >-
        One row of aggregated billing consumption returned by `GET
        /billing/consumption`.
      required:
        - period
        - product
        - total_amount_cents
        - count
      properties:
        period:
          type: string
          description: >
            Bucket label. Format depends on the `group_by` query param: ISO date
            (`2026-05-07`), ISO month (`2026-05`), or `total` for an ungrouped
            sum.
          example: '2026-05-07'
        product:
          type: string
          enum:
            - voice_call
            - eval_run
            - phone_number
            - topup
            - refund
            - other
          description: >
            Product category aggregated. `voice_call` covers paid call minutes,
            `eval_run` is agent-eval runs, `phone_number` is monthly number
            rent, `topup` is positive credit purchases (excluded by default —
            opt in with `include_topups=true`), `refund` is reverse charges.
        total_amount_cents:
          type: integer
          description: Sum of charges in cents for this bucket. Negative for refunds.
        count:
          type: integer
          description: Number of underlying transactions contributing to this bucket.
        agent_id:
          type: string
          format: uuid
          nullable: true
          description: Present when the request grouped by agent.
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````