Hosted Document Jobs: Lifecycle, Status, and Expiry

When you use the hosted FileRouter API, your parse or compare request does not execute inline — it creates a job that runs durably in the background. The job has a unique UUID, moves through a defined set of statuses, and stores its result in temporary cloud storage until you retrieve it. This model lets you fire off long-running parses without holding an open HTTP connection, and it means the SDK can safely retry polling without risk of submitting the same work twice.

Job lifecycle

Every job follows a linear path from creation to completion:

job-lifecycle.txt

queued → running → complete
                 ↘ failed

queued

The job has been accepted and persisted. The provider has not been contacted yet. This is the initial status returned when you POST /api/v1/jobs.

running

The job has been picked up and a request has been sent to the provider. The provider is actively processing the document.

complete

The provider returned a successful result. The normalized ParseResult (or CompareResult) is stored and available to retrieve.

failed

The provider returned an error, or the job encountered an unrecoverable problem. The error message is stored alongside the job record.

If you use the TypeScript SDK (FileRouterClient), you never need to manage polling yourself. The client’s parse() and compare() methods create the job, poll until it reaches complete or failed, and return the result (or throw an error) directly. Manual polling is only necessary if you call the REST API directly.

Using the TypeScript client

The FileRouterClient handles the full job lifecycle for you:

hosted-client.ts

import { FileRouterClient } from "@file_router/sdk"

const client = new FileRouterClient({
  apiKey: process.env.FILEROUTER_API_KEY,
})

// Creates a job, polls until complete, and returns the ParseResult
const result = await client.parse("https://example.com/report.pdf", {
  outputs: ["markdown", "pages"],
  provider: "llamaparse",
})

console.log(result.outputs.markdown)

The client polls on a 1-second interval by default. You can adjust this with pollingIntervalMs when constructing the client. If the job does not complete within the timeout window (default 10 minutes), the client throws a FileRouterError with code "Timeout".

client-with-timeout.ts

import { FileRouterClient } from "@file_router/sdk"

const client = new FileRouterClient({
  apiKey: process.env.FILEROUTER_API_KEY,
  pollingIntervalMs: 2000,  // poll every 2 seconds
})

const result = await client.parse(file, {
  outputs: ["markdown"],
  timeoutMs: 5 * 60 * 1000,  // override default 10-minute timeout
})

REST API

If you use the REST API directly, you create and poll jobs with two endpoints:

Create a job
Poll a job

POST /api/v1/jobsSend a JSON body to parse a document from a public URL:

create-job.json

{
  "operation": "parse",
  "source": { "url": "https://example.com/report.pdf" },
  "outputs": ["markdown", "pages"],
  "provider": "llamaparse"
}

Or send a binary body with X-FileRouter-* headers for file uploads. You must include the Idempotency-Key header on every request (see below).A 202 Accepted response means the job was created. A 200 OK response means an existing job was returned for your idempotency key.

job-accepted.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

GET /api/v1/jobs/{jobId}Poll this endpoint until status is "complete" or "failed":

job-complete.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete",
  "result": { ... }
}

job-failed.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Provider returned an error: ..."
}

While the job is still in progress, the response contains only id and status (either "queued" or "running"). Keep polling until the status changes.

Idempotency

Every job creation request requires an Idempotency-Key header. The key must be between 8 and 255 characters long (after trimming whitespace). If you send two requests with the same idempotency key, the second request returns the existing job without creating a new one (HTTP 200). This makes it safe to retry a failed network request — you will not accidentally submit the same document twice or be charged twice.

The TypeScript SDK generates a UUID idempotency key automatically for every parse() and compare() call. You only need to supply your own key if you want to control retry behavior manually — for example, to reuse the same key across a retry loop in your own code.

You can supply a custom key via idempotencyKey in HostedParseOptions or HostedCompareOptions:

custom-idempotency-key.ts

import { FileRouterClient } from "@file_router/sdk"

const client = new FileRouterClient({ apiKey: process.env.FILEROUTER_API_KEY })

// Using a stable key lets you safely retry this call
const result = await client.parse(file, {
  outputs: ["markdown"],
  idempotencyKey: "my-pipeline-run-2024-07-01-report-v3",
})

Result retention and expiry

Results expire after 7 days

The normalized parse result is stored for 7 days after the job completes. After that, a GET /api/v1/jobs/{jobId} request returns HTTP 410 Gone. Retrieve and persist results before they expire.

Job records kept for 30 days

The job metadata record (ID, status, timing) is retained for 30 days after creation. After 30 days the job record itself is removed.

Source documents are deleted on completion

The document you uploaded is deleted from cloud storage as soon as the job finishes — regardless of whether it succeeded or failed. FileRouter does not retain your source files.

Retrieve results before they expire

If your workflow needs the result beyond 7 days, download and store it in your own storage after the job completes.

A 410 Gone response on GET /api/v1/jobs/{jobId} means the result has expired and can no longer be retrieved. Plan your retrieval workflow to fetch results promptly after job completion.

Get Started

Core Concepts

TypeScript SDK

CLI

Guides

Hosted Document Jobs: Lifecycle, Status, and Expiry

Job lifecycle

Using the TypeScript client

REST API

Idempotency

Result retention and expiry

Results expire after 7 days

Job records kept for 30 days

Source documents are deleted on completion

Retrieve results before they expire

​Job lifecycle

​Using the TypeScript client

​REST API

​Idempotency

​Result retention and expiry

Results expire after 7 days

Job records kept for 30 days

Source documents are deleted on completion

Retrieve results before they expire

Job lifecycle

Using the TypeScript client

REST API

Idempotency

Result retention and expiry