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

# Query

> Ask natural-language questions about your documents

The Query endpoint lets you ask questions about your documents using natural language. Scope the query to a single document, a group (or multiple groups), or leave it unscoped to search your entire workspace.

## Query Documents

### Endpoint

`POST /api/v1/query`

### Scoping behaviour

| Parameters provided | Scope                                       |
| ------------------- | ------------------------------------------- |
| *(none)*            | All completed documents in your workspace   |
| `document_id`       | That document only (fastest)                |
| `group_id`          | All completed documents in that group       |
| `group_ids`         | All completed documents across those groups |

### Request Body

`application/json`

<ParamField body="query" type="string" required>
  Your natural-language question
</ParamField>

<ParamField body="document_id" type="string">
  Restrict the query to a single document.
</ParamField>

<ParamField body="group_id" type="string">
  Restrict the query to documents in a specific group. Cannot be combined with `document_id` or `group_ids`.
</ParamField>

<ParamField body="group_ids" type="string[]">
  Restrict the query to documents across multiple groups. Cannot be combined with `document_id` or `group_id`.
</ParamField>

### Response

<ResponseField name="answer" type="string">
  The answer to your question
</ResponseField>

<ResponseField name="document_id" type="string">
  The document used to answer (present only for single-document queries)
</ResponseField>

### Examples

<CodeGroup>
  ```bash All documents theme={null}
  curl -X POST https://app.polyvia.ai/api/v1/query \
    -H "Authorization: Bearer poly_<your-key>" \
    -H "Content-Type: application/json" \
    -d '{"query": "What risks are mentioned across all reports?"}'
  ```

  ```bash Single document theme={null}
  curl -X POST https://app.polyvia.ai/api/v1/query \
    -H "Authorization: Bearer poly_<your-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "query":       "What is the executive summary?",
      "document_id": "k57abc123..."
    }'
  ```

  ```bash Group query theme={null}
  curl -X POST https://app.polyvia.ai/api/v1/query \
    -H "Authorization: Bearer poly_<your-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "query":    "What are the key findings?",
      "group_id": "g_finance"
    }'
  ```

  ```bash Multi-group query theme={null}
  curl -X POST https://app.polyvia.ai/api/v1/query \
    -H "Authorization: Bearer poly_<your-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "query":     "Compare the Q3 and Q4 results.",
      "group_ids": ["g_q3", "g_q4"]
    }'
  ```

  ```python Python SDK theme={null}
  from polyvia import Polyvia

  client = Polyvia(api_key="poly_...")

  # All documents
  answer = client.query("What risks are mentioned across all reports?")

  # Single document (fastest)
  answer = client.query("Summarise section 3.", document_id="doc_...")

  # Group
  answer = client.query("Key findings?", group_id="g_finance")

  # Multiple groups
  answer = client.query("Compare Q3 vs Q4.", group_ids=["g_q3", "g_q4"])

  print(answer.answer)
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  {
    "answer":      "The gross margin improved by 4 pp year-over-year, driven by...",
    "document_id": "k57abc123..."
  }
  ```
</ResponseExample>

<Note>
  Documents must have `status=completed` before they can be queried. Use the [Check Ingestion Status](/api-reference/endpoint/ingest) endpoint to confirm a document is ready.
</Note>