Execution API

The Execution API allows you to trigger your deployed API and process files through the defined workflow.

API Endpoint Details


Endpoint	`/deployment/api/<organization_id>/<api_name>/`
URL	`https://us-central.unstract.com/deployment/api/<organization_id>/<api_name>/`
Method	`POST`
Headers	`Authorization: Bearer <YOUR API KEY>`
Body	`multipart/form-data`

Request Parameters

Parameter	Type	Default	Required	Description
files	File	--	Yes	Specifies the file(s) to be processed. Note: Multiple files can be provided, but the result will be completed only after all files have been processed.
timeout	integer	0	No	Specifies how long to wait for the API to complete the operation before timing out. The value can range from 0 to 300 seconds. If omitted, the request will execute in the background without a timeout.
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.
tags	string	--	No	Comma-separated list of tags to associate with the execution. Sample: `tag1` Note: Tags must start with a letter and can only contain letters, numbers, underscores, and hyphens. Currently limited to 1 tag per request. This tags are useful for supporting the tag feature in LLMWhisperer, where we can track usages over the tags and use it as an auditing feature.

HTTP Status Codes

HTTP Status	Description	Content-Type
200	OK - The request was successful. The API will return the result in the response body.	`application/json`
400	Bad Request - The request could not be understood or was missing required parameters.	`application/json`
401	Unauthorized - Authentication failed or user does not have permission for the requested operation.	`application/json`
403	Forbidden - The API key is missing or invalid.	`application/json`
404	Not Found - The requested resource could not be found (Or Incorrect API URl)	`application/json`
422	Unprocessable Entity - Validation error, the input could not be processed.	`application/json`
500	Internal Server Error - An error occurred on the server.	`application/json`

API Response Structure

Base Response

Parameter	Type	Description
execution_status	string	The current status of the execution process
status_api	string (URL)	API endpoint URL to check the current execution status
error	string/null	Error messages if any occurred, `null` if no errors
result	array	List of processed files and their corresponding results.

File Processing Result Object

Parameter	Type	Description
file	string	Name of the processed file
status	string	Processing status of the individual file
error	string (Optional)	Detailed error description if processing failed
result	object	Contains metadata and the extracted output of the processing

Processing Metadata (Result → result.metadata)

Parameter	Type	Description
context	object	Contextual data used for LLM call, organized by prompt key
embedding	array	Metrics related to embedding generation (e.g., model, cost, token count)
extraction_llm	array	Details and cost breakdown for LLM extraction
file_name	string	Name of the processed file
highlight_data	object	Information on highlighted text, including position and content
required_fields	object	List of mandatory document fields
run_id	string	Unique identifier for the document processing run
output	object	Structured data extracted from the document

Embedding Metrics (Result → result.metadata.embedding)

Parameter	Type	Description
model_name	string	Name of the model used for embedding generation.
embedding_tokens	number	Total number of tokens used during the embedding process.
cost_in_dollars	string	Cost incurred for generating embeddings, represented in USD.

LLM Extraction Metrics (Result → result.metadata.extraction_llm)

Parameter	Type	Description
model_name	string	Name of the model used for the LLM extraction process.
input_tokens	number	Number of tokens processed as input.
output_tokens	number	Number of tokens generated as output.
total_tokens	number	The total number of tokens used
cost_in_dollars	string	Cost incurred during the LLM extraction process, represented in USD.

Execution Metadata (Result → metadata)

Parameter	Type	Description
source_name	string	Original file name as provided
source_hash	string	Unique hash for the file, ensuring integrity and tracking
organization_id	string	Unique identifier for the organization
workflow_id	string	Unique identifier for the workflow used
execution_id	string	Unique identifier for the workflow execution
file_execution_id	string	Unique identifier for specific file execution (same as `run_id`)
tags	array	List of custom tags applied during the execution process
total_elapsed_time	number	Total time (in seconds) taken to process the file.
tool_metadata	array (object)	Details of tools used during processing, including tool names, elapsed time, and output type

Sample response Structure

{
    "message": {
        "execution_status": "<Current status of the execution process (e.g., PENDING, COMPLETED)>",
        "status_api": "<API endpoint to check the current execution status>",
        "error": "<Error messages, if any; null if no errors>",
        "result": [
            {
                "file": "<Name of the processed file>",
                "status": "<Processing status of the file>",
                "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`	Task is in queue and waiting to be processed (async).
`EXECUTING`	Execution is in progress (async mode).
`COMPLETED`	Execution finished successfully (fully or partially).
`ERROR`	The API failed to execute completely.

Completed Execution with Results

Upon successful completion of the execution, the API provides a response containing detailed results. The execution_status field will be set to COMPLETED.

Sample response:

{
    "message": {
        "execution_status": "COMPLETED",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": [
            {
                "file": "<file_name>",
                "status": "Success",
                "result": {
                    "input_file": "<input_file_name>",
                    "result": "<execution result of the file>"
                },
                "metadata": {
                    "source_name": "<source file name>",
                    "source_hash": "<hash value of the file>",
                    "organization_id": "<organization_id>",
                    "workflow_id": "<workflow_id>",
                    "total_elapsed_time": "<total_time>",
                    "tool_metadata": "<list_of_tools_used_during_execution>"
                }
            }
        ]
    }
}

Execution Error

If an error occurs during the execution process, the response will provide details about each file that failed. This helps in understanding what went wrong and allows for corrective actions

sample response

{
    "message": {
        "execution_status": "ERROR",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": [
            {
                "file": "<file_name>",
                "status": "Failed",
                "error": "<Error details or hint>"
            }
        ]
    }
}

Next Steps:

Check Logs: To get more detailed information about the error, refer to the logs for the API using the provided execution_id.
Contact Admin: If the logs do not provide sufficient information or if further assistance is needed, contact the administrator for additional details.

Mixed Results

If the execution process results in a mix of successful and failed files, the response will include detailed results for each file. This allows you to see which files were processed successfully and which encountered issues.

{
    "message": {
        "execution_status": "COMPLETED",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": [
            {
                "file": "<file_name>",
                "status": "Failed",
                "error": "<Error details or hint>"
            },
            {
                "file": "<file_name>",
                "status": "Success",
                "result": {
                    "input_file": "<input_file_name>",
                    "result": "<execution result of the file>"
                },
                "metadata": {
                    "source_name": "<source file name>",
                    "source_hash": "<hash value>",
                    "organization_id": "<organization_id>",
                    "workflow_id": "<workflow_id>",
                    "total_elapsed_time": "<total_time>",
                    "tool_metadata": "<list_of_tools_used_during_execution>"
                }
            }
        ]
    }
}

Description of each response code with sample

Below are some common response codes and their meanings:

422: Client Error

This response indicates that the pipeline is inactive, and the execution cannot proceed.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "Pipeline 'testetl' is inactive, please activate the pipeline",
            "attr": null
        }
    ]
}

400: Missing File

This response occurs when the files parameter is missing or empty.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "File shouldn't be empty",
            "attr": null
        }
    ]
}

200: Executing in Background

This response is returned when the execution is still ongoing, and the results are not yet available.

{
    "message": {
        "execution_status": "EXECUTING",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": null
    }
}

200: Completed

This response is returned when execution is completed, and the results are available.

{
    "status": "COMPLETED",
    "message": []  // Results
}

200: Pending

This response indicates that the execution is queued but has not started.

{
    "message": {
        "execution_status": "PENDING",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": null
    }
}

400: Validation Error

A validation error occurs when an invalid parameter is passed, such as a non-integer value for timeout.

{
    "type": "validation_error",
    "errors": [
        {
            "code": "invalid",
            "detail": "A valid integer is required.",
            "attr": "timeout"
        }
    ]
}

403: Forbidden

The API key is missing or invalid, preventing the request from proceeding.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "Missing API key",
            "attr": null
        }
    ]
}

500: Server Error

A 500 Internal Server Error indicates that something went wrong on the server during the processing of the request. This is a general error when the server encounters an unexpected condition that prevents it from fulfilling the request.

401: Unauthorized

A 401 Unauthorized error is returned when the request lacks proper authentication credentials, such as a missing or invalid API key. This means that the user is not authorized to access the requested resource.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "Unauthorized",
            "attr": null
        }
    ]
}

404: Not Found

This response occurs when the API name or URL is invalid, meaning the requested resource could not be found on the server. This can happen if the API name in the URL is incorrect or does not exist. Ensure that the organization_id and api_name are correctly specified in the request URL.

invalid api name (invalid api url)

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "API not found",
            "attr": null
        }
    ]
}

Possible Causes:

The api_name is misspelled or does not match an existing API.
The organization_id is incorrect or does not exist in the system.
The API endpoint is not available or has been removed.

Solution:

Check the list of available APIs for the organization to confirm the correct name.

API Endpoint Details​

Request Parameters​

HTTP Status Codes​

API Response Structure​

Base Response​

File Processing Result Object​

Processing Metadata (Result → result.metadata)​

Embedding Metrics (Result → result.metadata.embedding)​

LLM Extraction Metrics (Result → result.metadata.extraction_llm)​

Execution Metadata (Result → metadata)​

Sample response Structure​

Possible Execution status​

Completed Execution with Results​

Execution Error​

Next Steps:​

Mixed Results​

Description of each response code with sample​

422: Client Error​

400: Missing File​

200: Executing in Background​

200: Completed​

200: Pending​

400: Validation Error​

403: Forbidden​

500: Server Error​

401: Unauthorized​

404: Not Found​

Possible Causes:​

Solution:​