Status API

Use the Status API to check the status of a running execution. This endpoint allows you to track the execution initiated via the Execution API.

Request

Endpoint	/deployment/api/<organization_id>/<api_name>
URL	https://us-central.unstract.com/deployment/api/<organization_id>/<api_name>/
Method	GET
Headers	Authorization: Bearer <YOUR API KEY>
Body	None

Parameters

Parameter	Type	Default	Required	Description
execution_id	string	--	Yes	The ID of the execution. You can find it in the Execution API response or the API Deployment logs.
include_metadata	boolean	false	No	If this parameter is true, metadata of the result is included; otherwise, it is not. Note: This flag works only with tools exported from Prompt Studio. It contains usage and cost details of the LLMs and embeddings used.

Example Curl Request

curl -X GET --location 'https://us-central.unstract.com/deployment/api/org_HJqNgodUQsA99S3A/dasda/?execution_id=e748d90f-af7d-4a98-813d-4c47344ff595' \
--header 'Authorization: Bearer <Your API Key>'

Response

Refer to Possible Execution Status for a complete list of execution statuses.

Important Note - HTTP Status Limitation

Current Limitation: EXECUTING and PENDING statuses incorrectly return HTTP 422 instead of HTTP 2XX. This will be fixed in a future version.

Status	Current Response	Will Change To
EXECUTING	422 ❌	200 OK
PENDING	422 ❌	200 OK
COMPLETED	200 OK ✅	No change
STOPPED	422 ✅	No change
ERROR	422 ✅	No change

Migration Guide - Future-Proof Your Code:

To prepare for the upcoming change, choose one of these approaches:

Option 1: Recommended - Check Response Body Status

// ✅ Best approach - always works regardless of HTTP status changes
function isExecutionInProgress(responseBody) {
    const status = responseBody.status;
    return status === 'EXECUTING' || status === 'PENDING';
}

Option 2: If You Must Use HTTP Status Codes

// ✅ Future-proof HTTP status approach
function isExecutionInProgress(httpStatus, responseBody) {
    const status = responseBody.status;
    
    // Handle both current (422) and future (200) HTTP status codes
    if ((httpStatus === 422 || httpStatus === 200) && 
        (status === 'EXECUTING' || status === 'PENDING')) {
        return true;
    }
    
    return false;
}

Key Points:

• Primary Recommendation: Check the status field in the response body - this never changes
• Only EXECUTING/PENDING are affected: All other statuses (COMPLETED, ERROR, STOPPED) keep their current HTTP status codes
• Deploy Immediately: Both approaches work now and will continue working after the fix

Example 200 Response

{
    "status": "COMPLETED",
    "message": [
        {
            "file": "abc.pdf",
            "status": "Success",
            "result": {
                "input_file": "abc.pdf",
                "result": "unknown"
            },
            "metadata": {
                "source_name": "abc.pdf",
                "source_hash": "9bfb3c389658c442101e8c01c7f5eb722e2440297c490a63bf2a848083067da9",
                "organization_id": "ABCD",
                "workflow_id": "152d2209-af26-474b-b57b-1b786c8a046c",
                "execution_id": "<Id of execution at which the file actually executed without using file history>",
                "total_elapsed_time": "<total time of execution>",
                "tool_metadata": [
                    {
                        "tool_name": "classify",
                        "elapsed_time": "<Tool execution time>",
                        "output_type": "JSON"
                    }
                ]
            }
        }
    ]
}

Example with result-metadata

{
    "status": "COMPLETED",
    "message": [
        {
            "file": "invoice-nov.pdf",
            "status": "Success",
            "result": {
                "metadata": {
                    "context": {
                        // Contextual data useed for LLM call extracted from the document, organized by prompt key
                    },
                    "embedding": [
                        // Cost, token consumption, and other metrics related to embedding generation
                    ],
                    "extraction_llm": [
                        // Performance details and cost breakdown for the LLM-based extraction process
                    ],
                    "file_name": "<Name of the processed file>",
                    "line_numbers": {
                            // Information on highlighted text, including location and content
                    },
                    "required_fields": {
                        // Status and validation of mandatory document fields
                    },
                    "run_id": "<Unique identifier>", // Unique identifier for the processing run
                    "whisper_hash": "<Unique ID returned by Text extractor if LLMWhisperer used>"
                },
                "output": {
                        // Structured data extracted from the document
                    }
            },
            "error": "<Detailed error description if processing failed (Optional)>",
            "metadata": {
                "source_name": "<Original file name as provided>",
                "source_hash": "<Unique hash value for file integrity verification>",
                "organization_id": "<Unique identifier for the organization>",
                "workflow_id": "<Unique identifier for the workflow used>",
                "execution_id": "<Unique identifier for the workflow execution>",
                "file_execution_id": "<Unique identifier for this specific file execution same as run_id>",
                "tags": "<List of tags used during API execution>",
                "total_elapsed_time": "<Total time taken for processing the file in seconds>",
                "tool_metadata": "<Details of tools used during processing, including tool names, elapsed time, and output type>"
            }
        }
    ]
}

Possible Execution status

Status	Description
PENDING	The task has been queued for asynchronous execution. Check back later.
EXECUTING	The task is currently being executed. Please check again later.
COMPLETED	The execution has been successfully completed, either fully or partially.
STOPPED	The execution has been stopped or interrupted before completion.
ERROR	The API encountered an error during execution, or all file executions have failed.