Query your data

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)

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.

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"}'

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}")

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}`);

The response includes a status field that starts at PENDING:

{
  "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.

curl https://api.aiql.io/queries/YOUR_QUERY_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

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)

// 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));
}

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 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 for how to page through them.

curl https://api.aiql.io/queries \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

page = client.queries.list(limit=20)
for query in page.data:
    print(query.id, query.content, query.status)

const page = await client.queries.list({ limit: 20 });
for (const query of page.data) {
  console.log(query.id, query.content, query.status);
}

Delete a query

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

curl -X DELETE https://api.aiql.io/queries/YOUR_QUERY_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

client.queries.delete("YOUR_QUERY_ID")

await client.queries.delete("YOUR_QUERY_ID");

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.

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 for details.

Tools

Pipeline

Workspace

Embedding

Prerequisites

Create a query

Poll for completion

List saved queries

Delete a query

​Prerequisites

​Create a query

​Poll for completion

​List saved queries

​Delete a query

Prerequisites

Create a query

Poll for completion

List saved queries

Delete a query