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

# Prefect

> Connect Prefect so OpenSRE can inspect flow runs, workers, and deployments during incidents

## Overview

OpenSRE queries Prefect to retrieve recent flow runs (including logs for failed runs) and worker health — helping diagnose pipeline failures and identify stalled or crashed orchestration jobs.

## Prerequisites

* Prefect Cloud account or self-hosted Prefect Server
* API key (Prefect Cloud) or accessible API URL (self-hosted)

## Setup

There is no dedicated `opensre integrations setup prefect` wizard today. Configure via the persistent store (OpenSRE does not define product `PREFECT_*` env vars), then verify.

### Option 1: Persistent store

Add to `~/.opensre/integrations.json`:

```json theme={null}
{
  "version": 1,
  "integrations": [
    {
      "id": "prefect-prod",
      "service": "prefect",
      "status": "active",
      "credentials": {
        "api_url": "https://api.prefect.cloud/api",
        "api_key": "your-prefect-api-key",
        "account_id": "your-account-id",
        "workspace_id": "your-workspace-id"
      }
    }
  ]
}
```

| Field | Default | Description |
| - | - | - |
| `api_url` | `https://api.prefect.cloud/api` | Prefect API URL (override for self-hosted) |
| `api_key` | — | Prefect Cloud API key |
| `account_id` | — | Prefect Cloud account ID |
| `workspace_id` | — | Prefect Cloud workspace ID |

## Credentials

### Prefect Cloud

1. In Prefect Cloud, go to your **profile icon** → **API Keys**
2. Click **Create API Key**
3. Copy the key, account ID, and workspace ID from the URL: `https://app.prefect.cloud/account/<account-id>/workspace/<workspace-id>/`

### Self-hosted Prefect Server

Set `api_url` to your server's API endpoint (no API key required if unauthenticated):

```json theme={null}
{
  "api_url": "http://prefect-server:4200/api",
  "api_key": ""
}
```

## Tools

| Tool | What it does |
| - | - |
| `prefect_flow_runs` | Lists recent flow runs filtered by state (FAILED, CRASHED, etc.); can fetch logs for a specific run via `fetch_logs_for_run_id` |
| `prefect_worker_health` | Worker health and heartbeat status across work pools |

## Verify

```bash theme={null}
opensre integrations verify prefect
```

Expected output on success (self-hosted, `api_url` set):

```
Service: prefect
Status:  passed
Detail:  Configured for Prefect at http://prefect-server:4200/api.
```

For Prefect Cloud (only `api_key` set, no `api_url`):

```
Service: prefect
Status:  passed
Detail:  Configured for Prefect at cloud.
```

This is a **configuration-presence** check (`api_url` or `api_key` is set) — it does not call the Prefect API.

## Troubleshooting

| Symptom | Fix |
| - | - |
| **401 Unauthorized** | Check your API key and account/workspace IDs |
| **Connection refused** | Verify `api_url` is reachable — check firewall rules for self-hosted |
| **No flow runs returned** | Flow runs may have been purged — check retention settings |
| **Verify passed but tools fail** | Expected if credentials are present but wrong — confirm Cloud vs self-hosted fields |

## Security

* Use a **service account API key** rather than a personal key.
* For self-hosted, restrict network access to the Prefect API to trusted IPs.
* Store credentials in `~/.opensre/integrations.json`, not in source code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.