Sync vs Async
The v2 APIs give you two ways to run parsing and extraction work:- Synchronous: Call Parse or Extract and get the result in the response.
- Asynchronous: Create a Parse Job or Extract Job and collect the result when the job finishes.
Service Tiers
Every request runs on a service tier:priority or standard.
- The tier controls the turnaround time, the credit consumption rate, and which rate limit the request draws from.
- The tier does not change the supported file size or the number of pages allowed per file.
- Synchronous requests always run on the
prioritytier. - Jobs run on the
standardtier by default. Set theservice_tierparameter to run a job on theprioritytier.
Choose a Processing Mode and Service Tier
Use the table to choose the right call for your workload. Turnaround times are estimates, not guaranteed speeds. Rate limit values depend on your pricing plan; for the values and how each API meters usage, see Rate Limits. For per-page credit rates, see Credit Consumption.| Parse and Extract (synchronous) | Parse Jobs and Extract Jobs (asynchronous) | ||
|---|---|---|---|
| Service tier | Priority | Standard (default) | |
| Best for | Interactive workflows: a person or agent is waiting on the result | Time-sensitive work that a synchronous request can’t handle: larger documents, or when you don’t want to hold a connection open | Work with no one waiting: automated pipelines, background agent steps, scheduled ingestion |
| How you get the result | Inline in the response | Poll the job, or save the output to a URL | Poll the job, or save the output to a URL |
| Estimated turnaround time | Seconds to minutes | Seconds to minutes | Minutes to hours |
| Timeout limit | 475 seconds | 6 hours | 6 hours |
| Credit consumption | Full rate | Full rate | Half the priority rate |
| Parse limits per request | 100 pages; 50 MiB | 6,000 pages; 1 GiB for PDFs, 50 MiB for images | 6,000 pages; 1 GiB for PDFs, 50 MiB for images |
| Parse rate limit | Per-minute limit | Hourly limit; replenishes continuously | Hourly limit; resets each hour |
| Extract limits per request | No input size limit | No input size limit | No input size limit |
| Extract rate limit | Based on your plan and the input Markdown size | None: jobs are accepted immediately and paced internally | None: jobs are accepted immediately and paced internally |
Set the Service Tier
Parse and Extract do not accept theservice_tier parameter. To run a Parse Job or an Extract Job on the priority tier, set the service_tier parameter when you create the job.
Confirm the Service Tier
To confirm which tier a request ran on, checkmetadata.billing.service_tier in the response. See Parse API Response and Extract API Response.