# Fetch Failed Executions

Query your failed executions programmatically to build automated retry workflows, monitoring dashboards, or failure analysis tools.

This example shows how to filter executions by status and extract failure details, perfect for building resilient ML pipelines that automatically recover from transient errors.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* A Valohai project with some executions (successful or failed)
* Python 3.8+ and the `requests` library installed

### Generate a Valohai API Token <a href="#generate-a-valohai-api-token" id="generate-a-valohai-api-token"></a>

Create an API token to authenticate your requests:

1. Click **"Hi, \<username>!"** in the top-right corner
2. Go to **My Profile → Authentication**
3. Click **Manage Tokens** and scroll to the bottom
4. Click **Generate New Token**
5. Copy the token immediately — it's shown only once

Store your token as an environment variable:

```shell
# Linux/Mac
export VH_API_TOKEN=your_token_value

# Windows
set VH_API_TOKEN=your_token_value
```

### Get Your Project ID <a href="#get-your-project-id" id="get-your-project-id"></a>

Find your project ID in **Project Settings → General**

### Fetch Failed Executions <a href="#fetch-failed-executions-1" id="fetch-failed-executions-1"></a>

Create `fetch_failed_executions.py`:

```python
import requests
import json
import os

# Authenticate with your API token
auth_token = os.environ["VH_API_TOKEN"]
headers = {"Authorization": f"Token {auth_token}"}

# Replace with your project ID
project_id = "your-project-id-here"

# Fetch only failed executions
url = f"https://app.valohai.com/api/v0/executions/?project={project_id}&status=error"
resp = requests.get(url, headers=headers)
resp.raise_for_status()

# Print the response
print("Failed Executions:\n")
print(json.dumps(resp.json(), indent=4))
```

Run the script:

```shell
python fetch_failed_executions.py
```

### Understanding the Response <a href="#understanding-the-response" id="understanding-the-response"></a>

The API returns a paginated list of executions. Each failed execution includes:

```json
{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "exec-id-here",
      "counter": 42,
      "status": "error",
      "step": "train-model",
      "project": "project-id-here",
      "commit": "abc123...",
      "ctime": "2025-10-29T10:30:00Z",
      "duration": 125,
      "error_text": "Connection timeout during data download",
      "urls": {
        "display": "https://app.valohai.com/p/owner/project/execution/exec-id/"
      }
    }
  ]
}
```

**Key fields:**

* `status`: Always `"error"` when filtered by `status=error`
* `error_text`: Human-readable failure reason
* `step`: Which step failed
* `duration`: How long it ran before failing (in seconds)
* `urls.display`: Direct link to the execution in Valohai

### Status Filters <a href="#status-filters" id="status-filters"></a>

Query executions by different statuses:

```python
# All failed executions
status = error

# All successful executions
status = completed

# Manually stopped executions
status = stopped

# Currently running executions
status = started
```

### Next Steps <a href="#next-steps" id="next-steps"></a>

Now that you can fetch failed executions, you can:

* [Build automatic retry logic for transient failures](/automation-overview/rest-api/examples/retry-after-connection-error.md)
* Parse `error_text` to categorize failure types
* Send alerts when critical executions fail
* Generate daily failure reports

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

**Empty results:**

* Verify your project ID is correct
* Check that you have executions with `status=error`
* Try removing the status filter to see all executions

**Authentication errors:**

* Confirm `VH_API_TOKEN` environment variable is set
* Verify your token is valid in **My Profile → Authentication**

**Self-hosted Valohai:** Replace `https://app.valohai.com` with your installation URL


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/automation-overview/rest-api/examples/fetch-failed-executions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.