# aiCalls

query · in the family [Billing and the wallet](/reference/billing-and-the-wallet/)

## What it does

Your group’s AI calls with the words — what was asked, what the assistant said it understood, and what it answered — newest first, one page at a time.

YOUR group's AI calls WITH the words, NEWEST first (🧾 — THE AI LEDGER + the echo rule): the backwards month walk from this month to the 13-month floor (the rows live 13 months hot; the event lake keeps them forever). limit: 1..200, default 50. nextToken: the prior page's cursor VERBATIM (opaque, group-bound — a foreign or garbled token refuses VALIDATION/INVALID). month: ONE YYYY-MM bucket — the walk stays in it (nextToken null when it is exhausted). surface: one of the at.ai.call.v1 roster (e.g. office.report_draft) — a filter in the walk (a rare surface over a dense month may answer a SHORT page with a cursor: keep walking). day (YYYY-MM-DD, UTC) pins ONE calendar day of ONE bucket — the sk prefix, a bounded key read; with month they must agree. A16_BILLING by override; excluded from the consult tools and the read-only integration key.

## What happens

A read over the ledger the platform keeps for every AI call your group makes (thirteen months; nothing changes). Each row carries the person’s own words, what the model said it understood, the answer as the feature received it, the cost and the surface — the same facts the usage page totals by day, opened to the call. Owners and billing-plane roles read it; it is never offered to the AI as a tool and never granted to a read-only integration key.

## Who may call it

Capability area: **Billing and the wallet** — Your platform bill, token purchases and the usage and cost reads.

- Owner
- Manager
- Associate Manager
- An API key whose scope allows `api:aiCalls`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | [Int](/types/#scalars) | no | How many records to answer at most; a page may hold fewer. |
| `nextToken` | [String](/types/#scalars) | no | The cursor from the previous page, passed back exactly as received. |
| `month` | [String](/types/#scalars) | no | No further notes. |
| `surface` | [String](/types/#scalars) | no | No further notes. |
| `day` | [String](/types/#scalars) | no | No further notes. |

## Returns

[AiCallPage](/types/AiCallPage/) `AiCallPage!` — One page of YOUR group's AI calls, NEWEST first (the OrgBusEntryPage grammar).

This is a page: `items` holds the records and `nextToken` the cursor for the next page — pass it back verbatim until it is null. See [paging](/guides/paging-and-the-cursor-grammar/).

## Example request

```graphql
query ExampleAiCalls($limit: Int) {
  aiCalls(limit: $limit) {
    items {
      id
      at
      requestId
      op
      surface
      provider
      model
      effort
      schemaName
      status
      providerErrorCode
      costUsd
      priceTableVersion
      latencyMs
      bytesIn
      bytesOut
      prompt
      context
      contextTruncated
      understood
      answer
      answerTruncated
      userId
      sessionId
      organizationId
    }
    nextToken
  }
}
```

Variables:

```json
{
  "limit": 1
}
```

## Example response

```json
{
  "data": {
    "aiCalls": {
      "items": [
        {
          "id": "01900000-0000-7000-8000-37386ae00000",
          "at": "<at>",
          "requestId": "01900000-0000-7000-8000-3675ee9f0000",
          "op": "<op>",
          "surface": "<surface>",
          "provider": "<provider>",
          "model": "<model>",
          "effort": "<effort>",
          "schemaName": "Blue jeans",
          "status": "<status>",
          "providerErrorCode": "BJ-001",
          "costUsd": "<cost usd>",
          "priceTableVersion": "<price table version>",
          "latencyMs": 1,
          "bytesIn": 1,
          "bytesOut": 1,
          "prompt": "<prompt>",
          "context": "<context>",
          "contextTruncated": true,
          "understood": "<understood>",
          "answer": "<answer>",
          "answerTruncated": true,
          "userId": "01900000-0000-7000-8000-11f967df0000",
          "sessionId": "01900000-0000-7000-8000-be25a35a0000",
          "organizationId": "01900000-0000-7000-8000-44b781470000"
        }
      ],
      "nextToken": "<the cursor from the previous page>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))