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

# Runs

> List past runs and trigger ad-hoc runs.

```
GET  /v1/cofounder/runs
POST /v1/cofounder/runs
```

A "run" is one execution of the collector → reasoner → actor pipeline for one app. Runs are recorded in `cofounder_runs`.

## GET — list runs

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.appeeky.com/v1/cofounder/runs?appId=6479581124&limit=20 -H "X-API-Key: $KEY"
```

Query params:

| Param    | Default         | Notes             |
| -------- | --------------- | ----------------- |
| `appId`  | (all your apps) | Filter to one app |
| `limit`  | 20              | Max 100           |
| `offset` | 0               | For pagination    |

Response:

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "runs": [
      {
        "id": "uuid",
        "trigger_run_id": "run_abc123",        // Trigger.dev run id
        "owner_email": "you@example.com",
        "app_id": "6479581124",
        "trigger_source": "schedule",          // schedule | manual | event
        "event_type": null,
        "cadence": "daily",
        "status": "completed",                 // running | completed | failed
        "slack_thread_ts": "1714600000.123456",
        "error": null,
        "metrics": {
          "llmTokens": 6387,
          "costUsd": 0.0128,
          "toolCalls": 2,
          "durationMs": 12828
        },
        "started_at": "2026-05-02T08:00:00Z",
        "completed_at": "2026-05-02T08:00:13Z"
      }
    ],
    "total": 142
  }
}
```

## POST — trigger an ad-hoc run

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/cofounder/runs \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "appId": "6479581124",
    "country": "us",
    "analysisDepth": "deep"
  }'
```

Body:

| Field           | Required | Default           | Description                                       |
| --------------- | -------- | ----------------- | ------------------------------------------------- |
| `appId`         | Yes      | —                 | Apple App ID                                      |
| `country`       | No       | `us`              | ISO-2 country code                                |
| `analysisDepth` | No       | (your preference) | One-off override of `quick` / `standard` / `deep` |

Response (202):

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "triggered": true,
    "triggerRunId": "run_abc123"
  }
}
```

The actual analysis runs asynchronously in Trigger.dev. Poll the GET endpoint until `status: "completed"`.

## Errors

* `422 NOT_CONFIGURED` — you haven't called `PUT /preferences` yet
* `503 NOT_CONFIGURED` — Trigger.dev integration isn't configured server-side (system error)
* `502 TRIGGER_ERROR` — Trigger.dev rejected the request (check the body)