# assistantAsk

query · in the family [Reading your records](/reference/reading-your-records/)

## What it does

Ask the page assistant a question about using Almond Till — it knows which page you are on and answers with the same words the Guide shows.

Ask the page-aware assistant ONE written question about using AlmondTill/G3N: the answer grounds on the SAME guide corpus the Guide tab shows, WHERE you are and WHAT you look at, YOUR SESSION'S prior exchanges (the context follows your login session across pages — older exchanges condense into a rolling memory; the reply's contextTurns/contextTurnsMax/contextFolded carry the honest meter), and — when your role permits — LIVE READS of your own records requested by the assistant mid-answer (every read runs under YOUR permissions exactly as if you ran it; a read the assistant may run in the background is one you could run yourself). A READ-ONLY advisor: it can look things up, it never changes anything. Answers may link real pages from the app's own route directory. `question` is one written ask (<= 500 chars). Per-user hourly allowance (RATE_LIMIT/THROTTLED when spent). Refuses VALIDATION/INVALID at the full context (clear it and re-ask) and INTEGRATION/UNAVAILABLE while the assistant is offline/keyless — the Guide tab stands. Requires authentication (user sessions). Every made call is cost-metered (at.ai.call.v1).

## What happens

Advice only: it explains how to do things and may link the right pages, but it never changes anything itself. It sees which record you are viewing, not the record’s values. Each use makes one metered AI call, with an hourly allowance per person.

## Who may call it

Capability area: **Reading your records** — Looking up and listing the records of your organization.

- Owner
- System Administrator
- Manager
- Associate Manager
- Warehouse Associate
- Sales Associate
- An API key whose scope allows `api:assistantAsk`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `context` | [AssistantContextInput](/types/AssistantContextInput/) `AssistantContextInput!` | yes | No further notes. |
| `question` | [String](/types/#scalars) `String!` | yes | No further notes. |

## Returns

[AssistantAnswer](/types/AssistantAnswer/) `AssistantAnswer!` — The assistant's answer: grounded prose + up to five directory links. Advisory ONLY — nothing was changed on your behalf.

## Example request

```graphql
query ExampleAssistantAsk($context: AssistantContextInput!, $question: String!) {
  assistantAsk(context: $context, question: $question) {
    answer
    contextTurns
    contextTurnsMax
    contextFolded
  }
}
```

Variables:

```json
{
  "context": {
    "route": "<route>",
    "pageTitle": "Blue jeans",
    "specType": "<spec type>"
  },
  "question": "<question>"
}
```

## Example response

```json
{
  "data": {
    "assistantAsk": {
      "answer": "<answer>",
      "contextTurns": 1,
      "contextTurnsMax": 1,
      "contextFolded": true
    }
  },
  "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/))