GET /api/v1/jobs/{jobId} — Retrieve Job Status and Result

The GET /api/v1/jobs/{jobId} endpoint lets you check the status of a job and retrieve its result once parsing completes. Because FileRouter processes documents asynchronously, you call this endpoint repeatedly until the job transitions to complete or failed. The response shape changes depending on the job’s current status.

GET https://filerouter.dev/api/v1/jobs/{jobId}

The TypeScript FileRouterClient polls this endpoint automatically and resolves its promise when the job completes or rejects it when the job fails. You only need to poll manually when using the REST API directly from a non-TypeScript environment.

Path Parameters

jobId

string

required

The UUID of the job to retrieve. You get this value from the id field in the POST /api/v1/jobs response. Example: 550e8400-e29b-41d4-a716-446655440000.

Required Headers

Authorization

string

required

Bearer token authentication. Format: Bearer <your-api-key>. See Authentication for details.

Response Shapes by Status

The response body varies based on the job’s current status. Poll until you see "complete" or "failed".

queued / running
complete
failed

The job is in the queue or actively being processed. Continue polling.

In-progress job response

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

string

required

The UUID of the job.

status

string

required

Either "queued" (waiting to start) or "running" (currently processing).

The job finished successfully. The shape of the result field depends on whether the job was a parse or compare operation.

Parse job result (`ParseResult`)

Completed parse job response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "outputs": {
      "markdown": "# Annual Report 2024\n\nThis report covers..."
    },
    "pageCount": 12,
    "provider": "llamaparse",
    "timing": {
      "startedAt": "2024-01-15T10:00:00.000Z",
      "completedAt": "2024-01-15T10:00:04.500Z",
      "durationMs": 4500
    },
    "warnings": []
  }
}

string

required

The UUID of the job.

status

string

required

Always "complete" in this response shape.

result

object

required

The parse result object. Present only when status is "complete" and the job operation was "parse".

Show ParseResult fields

result.id

string

required

The job ID.

result.outputs

object

required

A map of output format IDs to their normalized values. The keys match the outputs array you specified when creating the job (e.g., { "markdown": "..." }).

result.pageCount

number

required

The number of pages processed in the document.

result.provider

string

required

The provider ID that processed the document (e.g., "llamaparse", "mistral-ocr").

result.timing

object

required

Timing information for the parse operation, with startedAt, completedAt (ISO 8601 strings), and durationMs (number).

result.warnings

array

required

Array of any warnings produced during parsing. Empty when there are none.

result.quality

object

Optional provider-native quality score with a score number and optional scale.

result.raw

unknown

The full raw provider response. Only present when includeRaw was true when creating the job.

Compare job result (`CompareResult`)

When the job operation was "compare", the result field contains a CompareResult — not a ParseResult. The key difference is the providers array, which holds one entry per provider that was run, each containing that provider’s individual ParseResult.

Completed compare job response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete",
  "result": {
    "input": "https://example.com/annual-report-2024.pdf",
    "outputs": ["markdown"],
    "providers": [
      {
        "provider": "llamaparse",
        "status": "parsed",
        "durationMs": 4200,
        "result": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "outputs": { "markdown": "# Annual Report 2024\n\n..." },
          "pageCount": 12,
          "provider": "llamaparse",
          "timing": {
            "startedAt": "2024-01-15T10:00:00.000Z",
            "completedAt": "2024-01-15T10:00:04.200Z",
            "durationMs": 4200
          },
          "warnings": []
        }
      },
      {
        "provider": "mistral-ocr",
        "status": "parsed",
        "durationMs": 3100,
        "result": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "outputs": { "markdown": "# Annual Report 2024\n\n..." },
          "pageCount": 12,
          "provider": "mistral-ocr",
          "timing": {
            "startedAt": "2024-01-15T10:00:00.000Z",
            "completedAt": "2024-01-15T10:00:03.100Z",
            "durationMs": 3100
          },
          "warnings": []
        }
      }
    ],
    "timing": {
      "startedAt": "2024-01-15T10:00:00.000Z",
      "completedAt": "2024-01-15T10:00:04.200Z",
      "durationMs": 4200
    }
  }
}

result

object

required

The compare result object. Present only when status is "complete" and the job operation was "compare".

Show CompareResult fields

result.input

string

required

The source document URL or identifier that was processed.

result.outputs

array

required

The list of output format IDs that were requested (e.g., ["markdown"]).

result.providers

array

required

One entry per provider that was run. Each entry has:

provider (string) — the provider ID
status ("parsed" | "failed" | "unsupported") — whether this provider succeeded
durationMs (number) — how long this provider took
result (ParseResult, optional) — the provider’s parse result, present when status is "parsed"
error (object, optional) — error details with message and optional code, present when status is "failed"

result.timing

object

required

Overall timing for the compare operation, with startedAt, completedAt (ISO 8601 strings), and durationMs (number).

The job encountered an error during processing. The error field contains a description of what went wrong.

Failed job response

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

string

required

The UUID of the job.

status

string

required

Always "failed" in this response shape.

error

string

A description of the error that caused the job to fail. May be null if the failure reason is unavailable.

Results expire after 7 days. Fetching a job whose result has expired returns HTTP 410 Gone. Download or store your results before the expiry window if you need them long-term.

Polling Example

Poll every few seconds until the job reaches a terminal status (complete or failed):

Polling loop (bash)

JOB_ID="550e8400-e29b-41d4-a716-446655440000"

while true; do
  RESPONSE=$(curl --silent \
    --header "Authorization: Bearer $FILEROUTER_API_KEY" \
    "https://filerouter.dev/api/v1/jobs/$JOB_ID")

  STATUS=$(echo "$RESPONSE" | jq -r '.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "complete" ]; then
    echo "Result:"
    echo "$RESPONSE" | jq '.result'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Job failed: $(echo "$RESPONSE" | jq -r '.error')"
    exit 1
  fi

  sleep 2
done

Error Responses

401 Unauthorized

The Authorization header is missing, invalid, or the key has been disabled or expired. See Authentication for details.

401 error body

{
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing FileRouter API key.",
  "title": "Unauthorized",
  "type": "https://filerouter.dev/problems/unauthorized",
  "instance": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

404 Not Found

No job with the given jobId exists for your account. Verify the UUID and ensure you’re using the same API key that created the job.

404 error body

{
  "status": 404,
  "code": "not_found",
  "detail": "No job found with the given ID.",
  "title": "Not Found",
  "type": "https://filerouter.dev/problems/not-found",
  "instance": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

410 Gone — Result expired

The job completed, but its result has passed the 7-day retention window and has been deleted. You can no longer retrieve the result for this job ID.

410 error body

{
  "status": 410,
  "code": "result_expired",
  "detail": "The result for this job has expired and is no longer available.",
  "title": "Gone",
  "type": "https://filerouter.dev/problems/result-expired",
  "instance": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

500 Internal Server Error

An unexpected server-side error occurred. The response includes a request_id — include it when contacting support.

Overview

Endpoints

GET /api/v1/jobs/{jobId} — Retrieve Job Status and Result

Path Parameters

Required Headers

Response Shapes by Status

Parse job result (`ParseResult`)

Compare job result (`CompareResult`)

Polling Example

Error Responses

​Path Parameters

​Required Headers

​Response Shapes by Status

​Parse job result (ParseResult)

​Compare job result (CompareResult)

​Polling Example

​Error Responses

Path Parameters

Required Headers

Response Shapes by Status

Parse job result (`ParseResult`)

Compare job result (`CompareResult`)

Polling Example

Error Responses