Asynchronous Processing

For large documents or production workflows, use async processing to avoid timeouts and handle long-running operations gracefully.

How It Works

Submit - Send your request with async: true
Receive job ID - Get an immediate response with a job_id
Poll - Check job status via GET /job/{jobId}
Get results - Retrieve completed results from the poll response

Endpoints with Async Support

Endpoint	Async Flag	Async Response
`POST /classify`	`async: true`	202 with `job_id`
`POST /extract`	`async: true`	202 with `job_id`
`POST /schema`	`async: true`	202 with `job_id`
`POST /tables`	`async: true`	202 with `job_id`
`POST /split`	`async: true`	202 with `job_id`

Using the Async Flag

Add async: true to any supported endpoint’s request body:

from pulse import Pulse

client = Pulse(api_key="YOUR_API_KEY")

# Async extraction
job = client.extract(
    file_url="https://example.com/large-report.pdf",
    async_=True  # Note: async_ in Python (async is reserved)
)
print(f"Job ID: {job.job_id}")
print(f"Status: {job.status}")  # "pending"

# Async schema extraction
job = client.schema(
    extraction_id="abc123",
    schema_config={"input_schema": {...}, "schema_prompt": "..."},
    async_=True
)

# Async split
job = client.split(
    extraction_id="abc123",
    split_config={"split_input": [{"name": "financials", "description": "..."}]},
    async_=True
)

import { PulseClient } from 'pulse-ts-sdk';

const client = new PulseClient({ 
    apiKey: 'YOUR_API_KEY'
});

// Async extraction
const job = await client.extract({
    fileUrl: "https://example.com/large-report.pdf",
    async: true
});
console.log(`Job ID: ${job.job_id}`);

// Async schema extraction
const schemaJob = await client.schema({
    extraction_id: "abc123",
    schema_config: { input_schema: {}, schema_prompt: "Extract details" },
    async: true
});

# Async extraction
curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/report.pdf",
    "async": true
  }'

# Response: {"job_id": "abc123", "status": "pending"}

Async Response Format

When async: true, you receive a 202 Accepted response:

{
  "job_id": "abc123-def456-ghi789",
  "status": "pending"
}

Field	Type	Description
`job_id`	string	Unique identifier for the async job
`status`	string	Initial status: `pending` or `processing`

Polling for Results

Use GET /job/{jobId} to check status and retrieve results:

import time

job_id = job.job_id

while True:
    status = client.jobs.get_job(job_id=job_id)
    print(f"Status: {status.status}")
    
    if status.status == "completed":
        print("Done!")
        print(f"Result: {status.result}")
        break
    elif status.status == "failed":
        print(f"Failed: {status.error}")
        break
    elif status.status == "canceled":
        print("Job was canceled")
        break
    
    time.sleep(2)  # Poll every 2 seconds

const pollForResult = async (jobId: string) => {
    while (true) {
        const status = await client.jobs.getJob({ jobId });
        console.log(`Status: ${status.status}`);
        
        if (status.status === 'completed') {
            return status.result;
        } else if (status.status === 'failed') {
            throw new Error(status.error);
        } else if (status.status === 'canceled') {
            throw new Error('Job canceled');
        }
        
        await new Promise(r => setTimeout(r, 2000));
    }
};

const result = await pollForResult(job.job_id);

# Poll for status
curl "https://api.runpulse.com/job/abc123-def456" \
  -H "x-api-key: YOUR_API_KEY"

Poll Response

{
  "job_id": "abc123-def456-ghi789",
  "status": "completed",
  "created_at": "2026-02-04T10:30:00Z",
  "completed_at": "2026-02-04T10:30:45Z",
  "result": {
    "markdown": "# Document Content...",
    "page_count": 50,
    "bounding_boxes": {...}
  }
}

Job Status Values

Status	Description
`pending`	Job is queued, waiting to start
`processing`	Job is currently running
`completed`	Job finished successfully - results available. May include `failed_pages` when specific pages were unextractable (see Partial Results)
`failed`	Job encountered an error
`canceled`	Job was canceled by user
`expired`	Job passed its retention window

Retention

Async results remain retrievable until your organization’s retention window for async jobs elapses, after which the job reads as expired. Retention applies to everything the job created: the stored result, URL-delivered (offloaded) result payloads, and any staged copy of the source document. Organizations can also opt into delete-on-first-poll, which removes a job’s stored artifacts as soon as the completed result is successfully retrieved once — download and persist the result on first read if your organization uses it. Contact support to configure retention for your organization.

Canceling Jobs

Cancel a running job with DELETE /job/{jobId}:

client.jobs.cancel_job(job_id=job_id)

curl -X DELETE "https://api.runpulse.com/job/abc123" \
  -H "x-api-key: YOUR_API_KEY"

When to Use Async

Large documents (50+ pages)

Synchronous requests may timeout for large documents. Always use async for documents over 50 pages.

Complex schemas

Schema extraction with many fields or nested structures benefits from async processing.

Production workflows

Async provides better reliability and allows you to handle failures gracefully with retries.

Batch processing

Submit multiple documents asynchronously and poll for results in parallel.

Sync vs Async Comparison

Aspect	Sync (`async: false`)	Async (`async: true`)
Response	Full result	Job ID only
HTTP Status	200	202
Timeout risk	Higher	Lower
Best for	Small docs, testing	Production, large docs
Polling needed	No	Yes

Webhooks Alternative

Instead of polling, you can use webhooks to receive notifications when jobs complete:

# Generate a one-time link to the Svix webhook portal
webhook_link = client.webhooks.create_webhook_link()
print(f"Configure webhooks at: {webhook_link.link}")

# Submit async job - webhook will notify on completion
job = client.extract(file_url="...", async_=True)

See Svix Webhooks for setup instructions.

API Reference

Pipeline Steps

Batch & Pipelines

Forms

Jobs, Results & Webhooks

Account & Usage

Async Processing

Asynchronous Processing

How It Works

Endpoints with Async Support

Using the Async Flag

Async Response Format

Polling for Results

Poll Response

Job Status Values

Retention

Canceling Jobs

When to Use Async

Sync vs Async Comparison

Webhooks Alternative

​Asynchronous Processing

​How It Works

​Endpoints with Async Support

​Using the Async Flag

​Async Response Format

​Polling for Results

​Poll Response

​Job Status Values

​Retention

​Canceling Jobs

​When to Use Async

​Sync vs Async Comparison

​Webhooks Alternative

Asynchronous Processing

How It Works

Endpoints with Async Support

Using the Async Flag

Async Response Format

Polling for Results

Poll Response

Job Status Values

Retention

Canceling Jobs

When to Use Async

Sync vs Async Comparison

Webhooks Alternative