> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kineticsystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Executions

> An execution is a single run of a workflow.

For detailed documentation, please see [Executions API Reference](../api-reference).

## Definition

An execution is a single run of a workflow. A workflow can have multiple executions.

An execution can be in one of the following states:

* `pending`: the execution is waiting to be queued
* `queued`: the execution is queued for processing
* `running`: the execution is currently running
* `completed`: the execution has terminated, and successfully completed the workflow
* `failed`: the execution has terminated, and failed to complete the workflow

## Lifecycle

An Execution goes through the following states: `pending` → `queued` → `running` → `completed` or `failed`.

* **Create**: POST `/api/workflows/{id}/execute` creates an execution and appends it to a queue for processing. You can also create an execution manually via the [Kinetic dashboard](https://kineticsystems.ai).
* **Retry**: POST `/api/executions/{executionId}/retry` will retry a prior execution. In practice, this works by cloning the current execution's details, stopping it, then queueing the newly created execution.
* **Logs**: GET `/api/executions/{executionId}` returns logs from the execution.

## Inputs

You can pass execution-specific inputs via the `inputPayload` field when creating an execution.

## Outputs

The following information is returned when an execution is retrieved:

* `status`: the status of the execution
* `duration_ms`: the duration of the execution in milliseconds
* `n_steps`: the number of steps in the execution
* `n_agent_actions`: the number of agent actions in the execution
* `n_screenshots`: the number of screenshots in the execution
* `output_url`: the URL of the output of the execution
* `video_url`: the URL of the video of the execution
* `logs_url`: the URL of the logs of the execution

## How it Works

When an execution is created, we follow these steps:

1. We create the execution record in the database, and set its status to `pending`.
2. We append the execution to a queue for processing, and set its status to `queued`.
3. Once resources are available, we spawn a worker container to execute the execution, and set its status to `running`.
4. The agent runs inside the container and executes the steps of the workflow. While executing, we log the actions taken by the agent.
5. After the execution terminates (either due to success or failure), we spin down the container, and set its status to `completed` or `failed`.

## Current Limitations

TODO -- add limitations