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

# Query your data

> Run natural-language queries over data you have ingested into a workspace

Queries run over the data you have already ingested into a workspace. You describe what you want in natural language, and AiQL returns the matching results. Queries are processed asynchronously through a workflow, so you poll for completion to get the result.

## Prerequisites

* An AiQL API key in the `AIQL_API_KEY` environment variable
* A workspace ID with a finished ingestion (see [Run a full ingestion](/cookbooks/ingestion))

## Create a query

Send your request as `content` and pass the workspace ID in the `AiQL-Workspace` header. The query is created with status `PENDING` and begins processing immediately.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.aiql.io/queries \
    -H "Authorization: Bearer $AIQL_API_KEY" \
    -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
    -H "Content-Type: application/json" \
    -d '{"content": "list every invoice over $1,000 from last quarter"}'
  ```

  ```python Python theme={null}
  import os
  from aiql import AiQL

  client = AiQL(api_key=os.environ["AIQL_API_KEY"])

  query = client.queries.create(
      workspace_id="YOUR_WORKSPACE_ID",
      content="list every invoice over $1,000 from last quarter",
  )

  print(f"Query created with status: {query.status}")
  ```

  ```typescript TypeScript theme={null}
  import { AiQL } from "@aiql.io/sdk";

  const client = new AiQL({ apiKey: process.env.AIQL_API_KEY });

  const query = await client.queries.create({
    workspaceId: "YOUR_WORKSPACE_ID",
    content: "list every invoice over $1,000 from last quarter",
  });

  console.log(`Query created with status: ${query.status}`);
  ```
</CodeGroup>

The response includes a `status` field that starts at `PENDING`:

```json theme={null}
{
  "id": "abc123",
  "content": "list every invoice over $1,000 from last quarter",
  "output": null,
  "status": "PENDING"
}
```

## Poll for completion

Queries are processed asynchronously. Poll the query by ID to check its status and retrieve the result when ready.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.aiql.io/queries/YOUR_QUERY_ID \
    -H "Authorization: Bearer $AIQL_API_KEY" \
    -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
  ```

  ```python Python theme={null}
  import time

  # Poll until processed
  while True:
      result = client.queries.get(query.id)
      
      if result.status == "PROCESSED":
          print(result.output)
          break
      elif result.status == "FAILED":
          print("Query failed")
          break
      
      time.sleep(2)
  ```

  ```typescript TypeScript theme={null}
  // Poll until processed
  while (true) {
    const result = await client.queries.get(query.id);
    
    if (result.status === "PROCESSED") {
      console.log(result.output);
      break;
    } else if (result.status === "FAILED") {
      console.log("Query failed");
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  ```
</CodeGroup>

The query moves through these statuses:

* `PENDING` → waiting to start
* `PROCESSING` → workflow is running
* `PROCESSED` → completed, result in `output` field
* `FAILED` → workflow failed

See [Query status lifecycle](/query-status) for the full state diagram and transitions.

## List saved queries

Retrieve the queries you have run in a workspace. Results are returned a page at a time — see [Pagination](/pagination) for how to page through them.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.aiql.io/queries \
    -H "Authorization: Bearer $AIQL_API_KEY" \
    -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
  ```

  ```python Python theme={null}
  page = client.queries.list(limit=20)
  for query in page.data:
      print(query.id, query.content, query.status)
  ```

  ```typescript TypeScript theme={null}
  const page = await client.queries.list({ limit: 20 });
  for (const query of page.data) {
    console.log(query.id, query.content, query.status);
  }
  ```
</CodeGroup>

## Delete a query

Remove a saved query when you no longer need it. This also cancels the workflow if it's still running.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://api.aiql.io/queries/YOUR_QUERY_ID \
    -H "Authorization: Bearer $AIQL_API_KEY" \
    -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
  ```

  ```python Python theme={null}
  client.queries.delete("YOUR_QUERY_ID")
  ```

  ```typescript TypeScript theme={null}
  await client.queries.delete("YOUR_QUERY_ID");
  ```
</CodeGroup>

<Tip>
  Keep prompts focused and constrain the result set. Word counts include both your query input and the matched content returned, so a tighter query costs fewer credits.
</Tip>

<Note>
  Queries are billed at 10 credits per 1,000 words, with a minimum of 1 credit per query. Listing, retrieving, and deleting saved queries is free. See [Pricing](/pricing) for details.
</Note>