Universal information extraction - Asynchronous API

What can the asynchronous API do?

Process large size documents and complex schemas without maintaining long-running connections
Submit multiple documents in a single request for batch processing
Optimize resource utilization for large-scale document processing workflows

For single document processing with immediate results, use the synchronous API instead.

How asynchronous API is different from the synchronous API?

Limitation	Synchronous API	Asynchronous API
Maximum number of pages	100 pages	1,000 pages
Maximum file size	50MB	50MB
Maximum number of properties in schema	Up to 100 properties	Up to 5000 properties
Maximum number of characters in schema	Up to 15,000 characters	Up to 120,000 characters

How it works

Create Job

Create an async job by submitting multiple documents along with your extraction schema. The API returns a job_id immediately without waiting for processing to complete.

Request

curl -X POST "https://api.upstage.ai/v1/information-extraction/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=information-extract" \
  -F "schema=@schema.json" \
  -F "documents=@document1.pdf" \
  -F "documents=@document2.pdf"

Response

{
  "job_id": "9db7dd3b-e5b6-4abb-bb4c-18a2c318d607",
  "status": "CREATED",
  "created_at": "2025-05-22T06:49:28.250713+00:00",
  "message": "Job created successfully and processing has begun"
}

Supported file formats: PDF, JPEG, PNG, BMP, TIFF, HEIC, DOCX, PPTX, XLSX
Maximum file size per document: 50MB
Maximum pages per document: 1,000 pages
Maximum pixels per page: 200,000,000 pixels
Maximum documents per job: Up to 20 documents
Supported character sets: Alphanumeric, Hangul, and Hanja are fully supported. Hanzi and Kanji are in beta.

Hanja, Hanzi, and Kanji are writing systems based on Chinese characters. For more information, see this article.

Use the job_id to retrieve the job information. The job information will include the status, total documents, completed documents, created at, started at, and completed at. The status will be one of: CREATED, IN_PROGRESS, PARTIALLY_COMPLETED, COMPLETED, FAILED, or CANCELED. Once the job is completed, extraction results will be available in the response.

Request

curl "https://api.upstage.ai/v1/information-extraction/jobs/9db7dd3b-e5b6-4abb-bb4c-18a2c318d607" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "job_id": "9db7dd3b-e5b6-4abb-bb4c-18a2c318d607",
  "status": "IN_PROGRESS",
  "model": "information-extract",
  "total_documents": 2,
  "completed_documents": 1,
  "created_at": "2025-05-22T06:49:28.250713+00:00",
  "started_at": "2025-05-22T06:49:30.123456+00:00"
}

List Jobs

List extraction jobs with summarized information. Users can use limit and offset to get paginated results.

Request

curl "https://api.upstage.ai/v1/information-extraction/jobs?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total_count": 6,
  "items": [
    {
      "job_id": "2f6dc523-d9d3-4153-a4f0-f996bbd1e4af",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:10:25.520719+00:00",
      "started_at": "2025-05-23T06:10:25.947162+00:00",
      "completed_at": "2025-05-23T06:10:33.264153+00:00"
    },
    {
      "job_id": "d7ae0041-7134-4692-a6c2-c811dd5d6fe9",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:09:39.202481+00:00",
      "started_at": "2025-05-23T06:09:39.351697+00:00",
      "completed_at": "2025-05-23T06:09:40.493135+00:00"
    },
    {
      "job_id": "d2e652a6-cde2-452a-a65b-635fb4d92883",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:02:08.608249+00:00",
      "started_at": "2025-05-23T06:02:08.786102+00:00",
      "completed_at": "2025-05-23T06:02:09.789933+00:00"
    },
    {
      "job_id": "b8ad3756-3fc3-4160-90e5-9dfe831a73dc",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:01:13.208130+00:00",
      "started_at": "2025-05-23T06:01:13.817681+00:00",
      "completed_at": "2025-05-23T06:01:18.709885+00:00"
    },
    {
      "job_id": "db826303-130f-4645-92a1-d82d35f73399",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 5,
      "completed_documents": 4,
      "created_at": "2025-05-14T05:52:44.628007+00:00",
      "started_at": "2025-05-14T05:52:46.273991+00:00",
      "completed_at": "2025-05-14T05:54:06.790172+00:00"
    },
    {
      "job_id": "737f597c-28fa-4167-99fe-ad46ff47b9ca",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 5,
      "completed_documents": 5,
      "created_at": "2025-05-13T02:03:55.484095+00:00",
      "started_at": "2025-05-13T02:03:56.383257+00:00",
      "completed_at": "2025-05-13T02:04:24.152512+00:00"
    }
  ],
  "limit": 20,
  "offset": 0
}

API Endpoints

The asynchronous API provides three main endpoints:

Create Async Job

Submit multiple documents for batch processing

Retrieve Job

Get job status and results

List Jobs

List all your extraction jobs

Schema definition

Similar to the synchronous API, you need to define a schema for data extraction. The schema follows JSON Schema Syntax. For detailed instructions on writing a schema, see the Writing a schema page.

Additional parameters

The asynchronous API supports the same additional parameters as the synchronous API to enhance extraction capabilities:

mode: Choose between standard and enhanced extraction modes.
split: Enable document splitting to extract information from multiple documents contained within a single file.
location: Enable location coordinates to get the page number and bounding box coordinates for each extracted field.
confidence: Enable confidence scores to receive confidence scores ("high" or "low") for each extracted field, helping you assess the reliability of results.

# Create async job with enhanced mode and location coordinates
data = {
    "model": "information-extract",
    "schema": json.dumps(schema),
    "mode": "enhanced",  # Use enhanced mode
    "location": True,  # Get location coordinates
    "confidence": True  # Get confidence scores
}

response = requests.post(
    f"{BASE_URL}/async",
    headers=headers,
    files=files,
    data=data
)

Best practices

Batch similar documents together: Group documents of the same type or schema for more efficient processing
Store job IDs: Keep track of job IDs for later retrieval and auditing
Use appropriate polling intervals: Check job status every 5-10 seconds to balance responsiveness and API usage
Download results after successful completion: Download results after the job is completed to avoid waiting for the results to be generated.
Fix errors and retry failed jobs: Fix errors and retry failed jobs to improve the success rate.

Basic async job workflow

import requests
import time
import json

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.upstage.ai/v1/information-extraction"

# Step 1: Create async job
headers = {"Authorization": f"Bearer {API_KEY}"}
files = {
    "documents": [
        ("documents", open("document1.pdf", "rb")),
        ("documents", open("document2.pdf", "rb"))
    ]
}
data = {
    "model": "information-extract",
    "schema": json.dumps({
        "type": "object",
        "properties": {
            "bank_name": {
                "type": "string",
                "description": "The name of bank in bank statement"
            }
        }
    })
}

response = requests.post(f"{BASE_URL}/async", headers=headers, files=files, data=data)
job_data = response.json()
job_id = job_data["job_id"]
print(f"Job created: {job_id}")

# Step 2: Poll job status
while True:
    response = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=headers)
    job_info = response.json()
    status = job_info["status"]
    print(f"Job status: {status}")
    
    if status in ["COMPLETED", "FAILED", "CANCELED"]:
        break
    
    time.sleep(5)  # Wait 5 seconds before checking again

# Step 3: Retrieve results
if status == "COMPLETED":
    response = requests.get(
        f"{BASE_URL}/jobs/{job_id}?with_result=true",
        headers=headers
    )
    results = response.json()
    print(json.dumps(results, indent=2))

Frequently Asked Questions

Try Universal IE in Upstage Studio!

Test information extraction capabilities with your documents before integrating the API.

Ready to build?

✓ Get $10 on signup

✓ Create your API key instantly

✓ Quick test with example codes

Universal information extraction - Asynchronous API

What can the asynchronous API do?

Process large size documents and complex schemas without maintaining long-running connections
Submit multiple documents in a single request for batch processing
Optimize resource utilization for large-scale document processing workflows

For single document processing with immediate results, use the synchronous API instead.

How asynchronous API is different from the synchronous API?

Limitation	Synchronous API	Asynchronous API
Maximum number of pages	100 pages	1,000 pages
Maximum file size	50MB	50MB
Maximum number of properties in schema	Up to 100 properties	Up to 5000 properties
Maximum number of characters in schema	Up to 15,000 characters	Up to 120,000 characters

How it works

Create Job

Create an async job by submitting multiple documents along with your extraction schema. The API returns a job_id immediately without waiting for processing to complete.

Request

curl -X POST "https://api.upstage.ai/v1/information-extraction/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=information-extract" \
  -F "schema=@schema.json" \
  -F "documents=@document1.pdf" \
  -F "documents=@document2.pdf"

Response

{
  "job_id": "9db7dd3b-e5b6-4abb-bb4c-18a2c318d607",
  "status": "CREATED",
  "created_at": "2025-05-22T06:49:28.250713+00:00",
  "message": "Job created successfully and processing has begun"
}

Supported file formats: PDF, JPEG, PNG, BMP, TIFF, HEIC, DOCX, PPTX, XLSX
Maximum file size per document: 50MB
Maximum pages per document: 1,000 pages
Maximum pixels per page: 200,000,000 pixels
Maximum documents per job: Up to 20 documents
Supported character sets: Alphanumeric, Hangul, and Hanja are fully supported. Hanzi and Kanji are in beta.

Hanja, Hanzi, and Kanji are writing systems based on Chinese characters. For more information, see this article.

Retrieve Job

Request

curl "https://api.upstage.ai/v1/information-extraction/jobs/9db7dd3b-e5b6-4abb-bb4c-18a2c318d607" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "job_id": "9db7dd3b-e5b6-4abb-bb4c-18a2c318d607",
  "status": "IN_PROGRESS",
  "model": "information-extract",
  "total_documents": 2,
  "completed_documents": 1,
  "created_at": "2025-05-22T06:49:28.250713+00:00",
  "started_at": "2025-05-22T06:49:30.123456+00:00"
}

List Jobs

List extraction jobs with summarized information. Users can use limit and offset to get paginated results.

Request

curl "https://api.upstage.ai/v1/information-extraction/jobs?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total_count": 6,
  "items": [
    {
      "job_id": "2f6dc523-d9d3-4153-a4f0-f996bbd1e4af",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:10:25.520719+00:00",
      "started_at": "2025-05-23T06:10:25.947162+00:00",
      "completed_at": "2025-05-23T06:10:33.264153+00:00"
    },
    {
      "job_id": "d7ae0041-7134-4692-a6c2-c811dd5d6fe9",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:09:39.202481+00:00",
      "started_at": "2025-05-23T06:09:39.351697+00:00",
      "completed_at": "2025-05-23T06:09:40.493135+00:00"
    },
    {
      "job_id": "d2e652a6-cde2-452a-a65b-635fb4d92883",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:02:08.608249+00:00",
      "started_at": "2025-05-23T06:02:08.786102+00:00",
      "completed_at": "2025-05-23T06:02:09.789933+00:00"
    },
    {
      "job_id": "b8ad3756-3fc3-4160-90e5-9dfe831a73dc",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 1,
      "completed_documents": 1,
      "created_at": "2025-05-23T06:01:13.208130+00:00",
      "started_at": "2025-05-23T06:01:13.817681+00:00",
      "completed_at": "2025-05-23T06:01:18.709885+00:00"
    },
    {
      "job_id": "db826303-130f-4645-92a1-d82d35f73399",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 5,
      "completed_documents": 4,
      "created_at": "2025-05-14T05:52:44.628007+00:00",
      "started_at": "2025-05-14T05:52:46.273991+00:00",
      "completed_at": "2025-05-14T05:54:06.790172+00:00"
    },
    {
      "job_id": "737f597c-28fa-4167-99fe-ad46ff47b9ca",
      "status": "COMPLETED",
      "model": "information-extract",
      "total_documents": 5,
      "completed_documents": 5,
      "created_at": "2025-05-13T02:03:55.484095+00:00",
      "started_at": "2025-05-13T02:03:56.383257+00:00",
      "completed_at": "2025-05-13T02:04:24.152512+00:00"
    }
  ],
  "limit": 20,
  "offset": 0
}

mode: Choose between standard and enhanced extraction modes.
split: Enable document splitting to extract information from multiple documents contained within a single file.
location: Enable location coordinates to get the page number and bounding box coordinates for each extracted field.
confidence: Enable confidence scores to receive confidence scores ("high" or "low") for each extracted field, helping you assess the reliability of results.

# Create async job with enhanced mode and location coordinates
data = {
    "model": "information-extract",
    "schema": json.dumps(schema),
    "mode": "enhanced",  # Use enhanced mode
    "location": True,  # Get location coordinates
    "confidence": True  # Get confidence scores
}

response = requests.post(
    f"{BASE_URL}/async",
    headers=headers,
    files=files,
    data=data
)

Best practices

Batch similar documents together: Group documents of the same type or schema for more efficient processing
Store job IDs: Keep track of job IDs for later retrieval and auditing
Use appropriate polling intervals: Check job status every 5-10 seconds to balance responsiveness and API usage
Download results after successful completion: Download results after the job is completed to avoid waiting for the results to be generated.
Fix errors and retry failed jobs: Fix errors and retry failed jobs to improve the success rate.

Basic async job workflow

import requests
import time
import json

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.upstage.ai/v1/information-extraction"

# Step 1: Create async job
headers = {"Authorization": f"Bearer {API_KEY}"}
files = {
    "documents": [
        ("documents", open("document1.pdf", "rb")),
        ("documents", open("document2.pdf", "rb"))
    ]
}
data = {
    "model": "information-extract",
    "schema": json.dumps({
        "type": "object",
        "properties": {
            "bank_name": {
                "type": "string",
                "description": "The name of bank in bank statement"
            }
        }
    })
}

response = requests.post(f"{BASE_URL}/async", headers=headers, files=files, data=data)
job_data = response.json()
job_id = job_data["job_id"]
print(f"Job created: {job_id}")

# Step 2: Poll job status
while True:
    response = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=headers)
    job_info = response.json()
    status = job_info["status"]
    print(f"Job status: {status}")
    
    if status in ["COMPLETED", "FAILED", "CANCELED"]:
        break
    
    time.sleep(5)  # Wait 5 seconds before checking again

# Step 3: Retrieve results
if status == "COMPLETED":
    response = requests.get(
        f"{BASE_URL}/jobs/{job_id}?with_result=true",
        headers=headers
    )
    results = response.json()
    print(json.dumps(results, indent=2))

Frequently Asked Questions

Try Universal IE in Upstage Studio!

Test information extraction capabilities with your documents before integrating the API.

Ready to build?

✓ Get $10 on signup

✓ Create your API key instantly

✓ Quick test with example codes

Universal information extraction - Asynchronous API

What can the asynchronous API do?

How asynchronous API is different from the synchronous API?

How it works

Create Job

Retrieve Job

List Jobs

API Endpoints

Create Async Job

Retrieve Job

List Jobs

Schema definition

Additional parameters

Best practices

Basic async job workflow

Frequently Asked Questions

On this page

Universal information extraction - Asynchronous API

What can the asynchronous API do?

How asynchronous API is different from the synchronous API?

How it works

Create Job

Retrieve Job

List Jobs

API Endpoints

Create Async Job

Retrieve Job

List Jobs

Schema definition

Additional parameters

Best practices

Basic async job workflow

Frequently Asked Questions

On this page

Create Async Job

Retrieve Job

List Jobs

Q. How long are job results stored?

Q. Can I cancel a running job?

Q. What happens if some documents fail?

Q. How many documents can I process in a single job?

Q. Can I use different schemas for different documents in the same job?

Q. How can I increase the rate limit?

On this page

Create Async Job

Retrieve Job

List Jobs

Q. How long are job results stored?

Q. Can I cancel a running job?

Q. What happens if some documents fail?

Q. How many documents can I process in a single job?

Q. Can I use different schemas for different documents in the same job?

Q. How can I increase the rate limit?

On this page