Run a full ingestion

An ingestion runs the full convert → split → shape → extract pipeline as a single managed job and loads the result into a workspace. You get orchestration, retries, and cancellation handling without chaining the tools yourself.

Prerequisites

An AiQL API key in the AIQL_API_KEY environment variable
A workspace ID (see Quickstart to create one)
A URL to the file AiQL can reach

Start the ingestion

Pass the file url and the workspace ID in the AiQL-Workspace header. Unlike the individual tools, ingestions operate on a workspace.

curl -X POST https://api.aiql.io/ingestions \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import os
from aiql import AiQL

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

ingestion = client.ingestions.create(
    workspace_id="YOUR_WORKSPACE_ID",
    url="https://example.com/report.pdf",
)
print(ingestion.id)

import { AiQL } from "@aiql.io/sdk";

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

const ingestion = await client.ingestions.create({
  workspaceId: "YOUR_WORKSPACE_ID",
  url: "https://example.com/report.pdf",
});
console.log(ingestion.id);

Poll for completion

Ingestions run asynchronously. Poll until the status reports the job is done. See the status lifecycle for every state an ingestion can report and the transitions between them.

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

ingestion = client.ingestions.get(ingestion.id)
print(ingestion.status)

const status = await client.ingestions.get(ingestion.id);
console.log(status.status);

Handle interruptions

Cancel a running ingestion, or retry one that failed. A cancelled job is only billed for the steps that finished; a retry only bills for the steps it re-runs.

curl -X POST https://api.aiql.io/ingestions/YOUR_INGESTION_ID/cancel \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

curl -X POST https://api.aiql.io/ingestions/YOUR_INGESTION_ID/retry \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

client.ingestions.cancel(ingestion.id)

client.ingestions.retry(ingestion.id)

await client.ingestions.cancel(ingestion.id);

await client.ingestions.retry(ingestion.id);

Next step

Once the ingestion finishes, query the data in your workspace. See the Quickstart for a query example.

An ingestion is billed as the sum of the steps it runs: convert per page, plus split, shape, and extract per 1,000 words. See Pricing for details.

Tools

Pipeline

Workspace

Embedding

Run a full ingestion

Prerequisites

Start the ingestion

Poll for completion

Handle interruptions

Next step

​Prerequisites

​Start the ingestion

​Poll for completion

​Handle interruptions

​Next step

Prerequisites

Start the ingestion

Poll for completion

Handle interruptions

Next step