Understanding sync and async API for Parse and Extract

When you call Agentic Document Extraction, you receive the following as output: parsed Markdown from Parse, or structured fields from Extract. The output stays unchanged regardless of how you call the API. What changes is how you wait for it. Send-and-hold-the-line is the simplest thing, but it doesn't scale to a several-thousand-page batch or a parse that outlives an HTTP timeout.

That's the whole story of sync versus async. It's a delivery choice — not a difference in the engine, the model, or the output. And it's tightly linked to a second choice you may already know from ADE's service tiers: Priority tier is offered both in sync and async mode, while the cheaper Standard and Batch tiers are both async by design. This post walks through the mechanism, then connects it back to those tiers so both decisions click into place at once.

Two ways to collect a result

Before the API terms, picture your favorite coffee shop.

You order a single latte and stand right at the counter until the barista slides it over — cup in hand before you take a step. One order, you wait, you walk away with the result. That's synchronous. It's perfect when it's just one drink and you want it now.

Now picture ordering forty coffees for the whole office. Nobody stands at the counter for that. You give your name, they hand you a little order number, and you go answer emails while the machines work. When the tray's ready, your number gets called and you collect the whole thing. That's asynchronous: drop off the request, take a ticket, come back for the finished order instead of holding up the line.

With that picture in mind, here's what the API terms mean.

Synchronous is one request, one response. You send the document (Parse) or the Markdown plus a schema (Extract), the connection stays open, and the finished result comes straight back down the same pipe. Nothing to track — you just read the response body. In ADE this is the plain parse and extract call. (That's the latte you waited at the counter for.)

Asynchronous is the office coffee run. You submit the work and immediately get back a job_id — that's your order number. Then you check back every 30 seconds until the job finishes, at which point its status flips to completed (or failed), and you pick up the result from there. In ADE these async endpoints have their own names: async Parse is parse jobs, and async Extract is extract jobs. Same two steps for both — submit, then poll.

The key point: same engine either way. Async Parse Jobs run the exact same DPT-3 parse and return the exact same response shape as a sync Parse. Async changes how you wait, not what you get.

Why async exists

Two reasons, both practical.

First, there's no live connection to babysit. A long parse or a big batch could easily outlast a request that would otherwise time out. Submit a job and the work runs server-side while your process moves on — a single Parse Job handles files up to 1 GB or 6,000 pages, well beyond what a synchronous call is meant to carry.

Second, async is where the cheaper service tiers live. The synchronous path always runs at the Priority rate, because someone is waiting on it. Move the same work to a job and you can set its service_tier to Standard — billed at roughly half the per-page rate — or, for bulk work, Batch(coming soon), the lowest rate of all. The output is identical; you're only choosing how soon you need it and what you're willing to pay for that. Extract Jobs exist for the same two reasons: long documents, or large and complex schemas you'd rather not hold a connection open for.

Parse: sync vs. async at a glance

For Parse, the difference comes down to when you get the response and where it lives.

When a job completes, small results come back inline under data; results over 1 MB come back as a presigned output_url you download. Extract mirrors this shape: a sync extract returns the values on the spot, while an Extract Job returns a job_id first and the finished values once the job reports done.

One thing to keep straight

Ordering never changes. Parse always runs first; Extract always runs on Parse's Markdown — regardless of whether either step is sync or async. Sync versus async is a delivery choice layered on top of that fixed order.

So you can mix modes freely: a sync Parse feeding an Extract Job, or an async Parse feeding a sync Extract. What you can't do is skip the order. Extract has nothing to work on until Parse has produced the Markdown.

How this maps to service tiers

Sync versus async isn't a separate decision from the service tier — it's the same decision seen from a different angle. The tier answers "how urgently do I need this, and what will I pay?" The delivery mode is how that answer shows up in your code. Line them up and the whole picture collapses into one table:

Back to the coffee shop for the tiers. The service tier is just how you pay for your place in the queue. Slip the barista a little extra to have your drink pulled next — that's Priority. Take your spot in the normal line — that's Standard. Or say "no rush, make these two hundred whenever it's quiet and give me the off-peak price" — that's Batch.

The quick recap — two modes, three tiers. Sync and async are how you wait; the three tiers are how much you pay for speed. They connect through one simple rule: Standard and Batch are async-only — there's no counter to wait at, you always take a ticket. Priority is the only tier that lets you wait at the counter (sync), though it'll hand you a ticket too (async) when the order's too big to hold. So: sync always means Priority; async can be any of the three.

The pattern to remember: sync is a Priority-only convenience. The moment you reach for Standard or Batch to save money, you're necessarily working asynchronously — submit, poll, collect. So the practical rule of thumb is to start from "who's waiting?" If a human or agent is blocked on the result, stay synchronous on Priority. If nothing is waiting, move the work to a job and drop to the cheaper tier. For the full tier breakdown — rate limits, cost multipliers, and when Batch makes sense — see the companion post on ADE service tiers.

Learn more

• ADE Documentation — sync parse/extract and the async parse jobs and extract jobs workflow.
• Plans & billing — how credits, tiers, and per-page rates work.
• Companion post: Choosing an ADE service tier — Priority, Standard, and Batch.