Async Processing

Overview

Every Aifano endpoint has an async variant (/parse_async, /extract_async, /split_async, /edit_async, /pipeline_async). Async endpoints return a job_id immediately, and you poll for results or receive them via webhook. Use async processing when:

Documents are large (50+ pages)
You’re processing batches of documents
You don’t need results immediately
You want to avoid request timeouts

Submitting an Async Job

Add _async to any endpoint:

curl -X POST "https://platform.aifano.com/parse_async" \
  -H "Authorization: Bearer $AIFANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "aifano://large-report.pdf"}'

import requests

job = requests.post(
    "https://platform.aifano.com/parse_async",
    headers={"Authorization": f"Bearer {AIFANO_API_KEY}"},
    json={"input": "aifano://large-report.pdf"}
).json()

print(f"Job submitted: {job['job_id']}")

const job = await fetch("https://platform.aifano.com/parse_async", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${AIFANO_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ input: "aifano://large-report.pdf" })
}).then(r => r.json());

console.log(`Job submitted: ${job.job_id}`);

Response

{
  "job_id": "job_a1b2c3d4e5f6"
}

Polling for Results

Use GET /job/{job_id} to check the status:

curl "https://platform.aifano.com/job/job_a1b2c3d4e5f6" \
  -H "Authorization: Bearer $AIFANO_API_KEY"

import time

while True:
    status = requests.get(
        f"https://platform.aifano.com/job/{job['job_id']}",
        headers={"Authorization": f"Bearer {AIFANO_API_KEY}"}
    ).json()

    if status["status"] in ("COMPLETED", "FAILED"):
        break

    print(f"Status: {status['status']}...")
    time.sleep(2)

if status["status"] == "COMPLETED":
    result = status["result"]

async function pollJob(jobId) {
  while (true) {
    const status = await fetch(
      `https://platform.aifano.com/job/${jobId}`,
      { headers: { "Authorization": `Bearer ${AIFANO_API_KEY}` } }
    ).then(r => r.json());

    if (status.status === "COMPLETED" || status.status === "FAILED") {
      return status;
    }

    await new Promise(r => setTimeout(r, 2000));
  }
}

Job Statuses

Status	Description
`PENDING`	Job is queued and waiting to be processed
`RUNNING`	Job is currently being processed
`COMPLETED`	Job finished successfully — results are available
`FAILED`	Job failed — check the `error` field for details

Completed Job Response

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "COMPLETED",
  "result": {
    "type": "full",
    "chunks": [...]
  }
}

Cancelling a Job

Cancel a running or pending job:

curl -X POST "https://platform.aifano.com/cancel/job_a1b2c3d4e5f6" \
  -H "Authorization: Bearer $AIFANO_API_KEY"

Async Endpoints

Sync Endpoint	Async Endpoint	Description
`POST /parse`	`POST /parse_async`	Document parsing
`POST /extract`	`POST /extract_async`	Data extraction
`POST /split`	`POST /split_async`	Document splitting
`POST /edit`	`POST /edit_async`	Document editing
`POST /pipeline`	`POST /pipeline_async`	Pipeline execution

Best Practices

Use reasonable polling intervals

Poll every 2–5 seconds. Avoid polling more frequently than once per second.

Set a polling timeout

Set a maximum number of polling attempts (e.g., 150 attempts × 2s = 5 minutes) to avoid infinite loops.

Handle failures gracefully

Always check for FAILED status and inspect the error field. Implement retry logic for transient errors.

Use async for batch processing

Submit all jobs first, then poll for results. This maximizes throughput and avoids sequential bottlenecks.

Get Started

Core Concepts

Configuration

Reference

Async Processing

Overview

Submitting an Async Job

Response

Polling for Results

Job Statuses

Completed Job Response

Cancelling a Job

Async Endpoints

Best Practices

​Overview

​Submitting an Async Job

​Response

​Polling for Results

​Job Statuses

​Completed Job Response

​Cancelling a Job

​Async Endpoints

​Best Practices

Overview

Submitting an Async Job

Response

Polling for Results

Job Statuses

Completed Job Response

Cancelling a Job

Async Endpoints

Best Practices