Skip to main content

​
What is an Execution?

An execution represents a single run of an assistant’s processing pipeline. When an event triggers an assistant — such as a document upload, a channel message, or a scheduled job — the platform creates an execution that processes the event through the assistant’s configured pipeline steps. Each execution tracks the full lifecycle from trigger to completion, including which steps ran, how long they took, and whether they succeeded or failed.

​
Execution Statuses

StatusValueDescription
PENDING0Created and waiting for the scheduler to plan it
RUNNING1Pipeline steps are being executed
SUCCEEDED2All steps completed successfully
FAILED3One or more steps failed or timed out
REQUESTED4Execution was requested but not yet created
SKIPPED5Execution was skipped (e.g., deduplication)
CANCELLING6Cancel was requested, waiting for running steps to stop
CANCELLED7Execution was cancelled
PENDING_REPROCESSING8Awaiting reprocessing
REPROCESSED9Reprocessing complete

​
Common Operations

​
List Executions for an Assistant

curl "https://platform.kodexa-enterprise.com/api/executions?filter=assistantId%20eq%20'{assistantId}'&sort=createdOn,desc&pageSize=20" \
  -H "x-api-key: your-api-key-here"

​
Get Execution Details

Retrieve an execution with its pipeline configuration, context, and status: 
curl "https://platform.kodexa-enterprise.com/api/executions/{executionId}" \
  -H "x-api-key: your-api-key-here"
The response includes: 
{
  "id": "abc-123",
  "status": "SUCCEEDED",
  "priority": 5,
  "startDate": "2026-02-25T10:00:00Z",
  "endDate": "2026-02-25T10:00:15Z",
  "pipeline": {
    "steps": [
      {
        "ref": "module://kodexa/pdf-parser",
        "name": "Parse PDF",
        "stepType": "MODEL"
      },
      {
        "ref": "module://kodexa/invoice-extractor",
        "name": "Extract Data",
        "stepType": "MODEL"
      }
    ]
  },
  "context": {
    "eventType": "CONTENT_CREATED",
    "documentFamilyId": "def-456",
    "storeId": "store-789",
    "taxonomyRefs": ["kodexa/invoice-taxonomy"]
  }
}

​
Cancel a Running Execution

Stop a running execution. Any in-progress steps will be cancelled: 
curl -X PUT "https://platform.kodexa-enterprise.com/api/executions/{executionId}/cancel" \
  -H "x-api-key: your-api-key-here"

​
List Executions for a Document Family

Find all executions that processed a specific document: 
curl "https://platform.kodexa-enterprise.com/api/executions?filter=documentFamilyId%20eq%20'{documentFamilyId}'" \
  -H "x-api-key: your-api-key-here"

​
Filter by Status

List only failed executions: 
curl "https://platform.kodexa-enterprise.com/api/executions?filter=status%20eq%20'FAILED'&sort=createdOn,desc" \
  -H "x-api-key: your-api-key-here"

​
Execution Context

The execution context contains metadata about the triggering event and is available to modules during processing:
FieldDescription
eventTypeThe event that triggered the execution
documentFamilyIdThe document family being processed
contentObjectIdThe specific content object that triggered the event
storeIdThe document store ID
channelIdThe channel ID (for channel events)
taskIdThe task ID (for task events)
taxonomyRefsTaxonomy references from the assistant configuration
completeLabelLabel to apply when processing completes

​
Reprocessing Documents

To reprocess a document family through one or more assistants, use the document family reprocess endpoint: 
curl -X PUT "https://platform.kodexa-enterprise.com/api/document-families/{familyId}/reprocess?assistantId={assistantId}" \
  -H "x-api-key: your-api-key-here"
This creates a new execution in PENDING status for each specified assistant.

​
Execution Priority

Executions are processed in priority order. Higher priority values are scheduled first. Within the same priority, older executions are processed first (FIFO). Event types are assigned default priorities — for example, content events are typically higher priority than scheduled job events.