Synchronous or asynchronous parsing? Choose a flow that fits your application

Start with what should happen while parsing runs

For a single link submitted from a review screen, your server may be able to wait and return either the result or a clear error to that interaction. For an import queue, the application usually needs to save the task and let other work continue while the source is being processed.

Synchronous and asynchronous submission use the same parsing request body and a stable Idempotency-Key. Both create account tasks with the same pricing rules. Waiting in one HTTP call does not make an inaccessible source available or remove the need to handle a failed parse.

Use one synchronous call for a bounded interaction

POST /v1/api/jobs/sync waits for a usable result. Success returns HTTP 200 with the same task detail structure as a single-task query; the task identifier in that response is id. A failed parse returns an error rather than a successful response containing a pending task.

The server wait is 30 seconds from acceptance, including the initial state snapshot and detail reading. Your HTTP client and gateway need additional time for submission, response transfer and cancellation cleanup; the documentation uses a 60-second cURL timeout. The synchronous endpoint accepts no query parameters for changing this wait.

Each API process has 64 synchronous wait slots. If they are occupied, HTTP 429 / SYNC_CAPACITY_EXCEEDED rejects the request before creating a task. Respect Retry-After, and consider asynchronous submission when many interactions need to wait at once. Account rate and concurrent-task limits still apply.

Let asynchronous tasks work independently, then query together

POST /v1/api/jobs returns HTTP 202 when a task is accepted. Save job_id with your own business record and query it later. This fits background imports, scheduled work and screens where the user can leave before parsing finishes.

POST /v1/api/jobs/batch reads 1–100 existing task IDs in one request. Items follow the input order, including duplicate IDs. Each item has its own http_status, job and error, so an unknown ID does not hide another task’s result. An item with http_status: 200 means the task detail was read; check job.status to decide whether parsing succeeded.

The complete uncompressed batch JSON response is limited to 16 MiB. Even fewer than 100 large results can exceed that budget, and repeated IDs count each time they appear. HTTP 422 / BATCH_RESPONSE_TOO_LARGE means you should request fewer IDs or split the batch. Batch queries read existing tasks and do not submit additional parsing work.

• Keep a set of unfinished job IDs and query it at a bounded interval.
• Remove terminal tasks from the polling set and handle each item’s error separately.
• Use backoff and honor Retry-After; batching does not remove the account’s request limits.

Distinguish a server cancellation from a lost response

A returned HTTP 504 / SYNC_TIMEOUT confirms that the server wait expired, the task was cancelled and its frozen credits were released without consumption. Reusing that task’s request key refers to the cancelled task; a deliberate new parse needs a new key. If completion wins before cancellation, the server preserves the actual result and settles a successful task normally.

A timeout in your own HTTP client or gateway, or a broken connection, does not confirm server cancellation. Keep the original body and Idempotency-Key, and use them to recover the same submission or inspect the known task. Changing the key immediately can create another task while the first is still running.

A 503 response also needs its specific error code. SYNC_CANCEL_UNCONFIRMED means cancellation was not confirmed; SYNC_CLEANUP_FAILED means cancellation is confirmed but credit release is still pending. Check the original task and wallet before deciding what action to take.

Keep parsing state and credit settlement understandable

Choosing synchronous submission does not add another parsing fee, and reading existing results with single or batch queries does not consume credits. Queries still count toward the account’s request rate. Successful parsing follows the documented task price; failure, cancellation, expiration or an empty paid result releases the reservation.

A successful HTTP response and the final credit transaction are not guaranteed to appear at exactly the same instant. Your application can show the returned result while using balance and ledger queries for account records. Do not treat a briefly frozen reservation after success as evidence that the task was charged twice.

Choose one path first, then add the recovery cases

For an interactive integration, begin with one synchronous request and test both a usable result and an explicit error. For a queue, begin with asynchronous submission, persist job_id, and add batch polling only after your application handles task states correctly.

In either flow, keep API keys on your server, retain the original source reference and test supported content you are authorized to process. The API documentation contains the complete request fields, response examples and error codes. A clear recovery action is more useful than automatically creating a new task for every timeout.