Get the status or result of a job

Retrieve a job status and its result when available. Review the result wrapper or request server-sent events to follow progress.

GET /api/v2/jobs/{jobId}

Get the status or result of a parse or extraction job

cURL

curl --request GET \
  --url https://transform.unstructured.io/api/v2/jobs/{jobId} \
  --header 'unstructured-api-key: <api-key>'

200

{
  "id": "9eb6c914-02a5-4c5d-8490-a06476946a38",
  "status": "queued",
  "file_id": "<string>",
  "filename": "<string>",
  "cancellation_requested": false,
  "source": {
    "file_id": "<string>",
    "filename": "<string>",
    "mimetype": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "error": {
    "code": "invalid_input",
    "message": "<string>"
  },
  "result": {
    "id": "<string>",
    "status": "processing",
    "profile": "balanced",
    "markdown": "<string>",
    "format_version": "2.0",
    "metadata": {
      "page_count": 123
    },
    "extracted_data": [
      {
        "data": "<unknown>",
        "field_metadata": {}
      }
    ],
    "elements": [
      {
        "element_id": "<string>",
        "type": "<string>",
        "text": "<string>",
        "metadata": {
          "page_number": 123,
          "coordinates": {},
          "text_as_html": "<string>"
        }
      }
    ],
    "source": {
      "file_id": "<string>",
      "filename": "<string>",
      "mimetype": "<string>",
      "expires_at": "2023-11-07T05:31:56Z"
    },
    "warnings": []
  }
}

Retrieve a job and read its status, error, and result. Request server-sent events to follow progress while it runs.

Start with Parse your first document.

Authorizations

ApiKeyAuthBearerAuth

unstructured-api-key · string · header · required

Path Parameters

jobId · string · required

Identifies one piece of work, whichever path submitted it. The same id the blocking call returns.

Example:

"9eb6c914-02a5-4c5d-8490-a06476946a38"

Query Parameters

output · enum<string> · default: markdown

Shape of the parsed output.

Available options: markdown, elements

include · string[]

Optional list of projection fields to include in elements output. Allowed values are 'coordinates' and 'table_html'. Only valid when output='elements'.

Response

200

application/json

The job's state, carrying parsed content as soon as it is available. As an event stream, progress events then one terminal result or error event.

A job's state, carrying parsed content as soon as it is available.

id · string · required

Identifies one piece of work, whichever path submitted it. The same id the blocking call returns.

Example:

"9eb6c914-02a5-4c5d-8490-a06476946a38"

status · enum<string> · required

Terminal values match the blocking call's own status values.

Available options: queued, processing, failed, completed, completed_with_warnings, cancelled

file_id · string | null · required

The authoritative source/input file ID. This is the ID accepted by GET /api/v2/upload/{fileId}, never a job ID, result artifact ID, storage key, or signed URL. Null for legacy or unassociated jobs.

filename · string | null

The document's original uploaded filename.

cancellation_requested · boolean · default: false

True after cancellation has been requested for this job.

source · object | null

The associated original uploaded source file, when known.

Show child attributes

error · object | null

A machine-readable code and an actionable message.

Show child attributes

result · object | null

Null until parsed content is available.

Show child attributes