> ## 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.

# Why (Root-Cause Analysis) API

> Trigger RCA runs and fetch structured cause reports.

```
POST /v1/cofounder/why
GET  /v1/cofounder/why/reports
GET  /v1/cofounder/why/reports/:id
```

See [Why-agent](../capabilities/why-agent) for the conceptual overview.

## POST — trigger an analysis

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/cofounder/why \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "appId": "6479581124",
    "metricPath": "asc.revenue",
    "timeRange": { "from": "2026-06-01T00:00:00Z", "to": "2026-07-01T00:00:00Z" },
    "userQuestion": "Why did US revenue drop after v2.4?"
  }'
```

Body:

| Field                             | Required | Description                                   |
| --------------------------------- | -------- | --------------------------------------------- |
| `appId`                           | Yes      | App ID                                        |
| `metricPath`                      | Yes      | e.g. `asc.revenue`, `asc.downloads`           |
| `timeRange.from` / `timeRange.to` | Yes      | ISO timestamps bounding the window to explain |
| `userQuestion`                    | No       | Sharpens the investigation                    |
| `signalId`                        | No       | Attach a triggering signal's context          |

Response (202):

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

The analysis runs async (typically 30–90 seconds). Poll the reports list until a new row appears.

## GET — list reports

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

Optional filters: `appId`, `metricPath`, `limit` (max 100).

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "reports": [
      {
        "id": "uuid",
        "app_id": "6479581124",
        "metric_path": "asc.revenue",
        "user_question": "Why did US revenue drop after v2.4?",
        "signal_id": null,
        "llm_tokens": 9214,
        "cost_usd": 0.011,
        "duration_ms": 48210,
        "created_at": "2026-07-01T10:00:00Z",
        "cache_until": "2026-07-02T10:00:00Z"
      }
    ]
  }
}
```

## GET — fetch one report

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.appeeky.com/v1/cofounder/why/reports/<id> -H "X-API-Key: $KEY"
```

The `report` field contains the structured analysis:

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "report": {
      "id": "uuid",
      "metric_path": "asc.revenue",
      "report": {
        "observation": "US revenue fell 34% between Jun 2 and Jun 9...",
        "candidateCauses": [
          {
            "summary": "v2.4 removed the onboarding discount",
            "likelihood": "very_likely",   // very_likely | likely | possible | unlikely
            "evidenceFor": ["Drop starts within 24h of v2.4 rollout", "..."],
            "evidenceAgainst": ["Trial starts unchanged"]
          }
        ],
        "topPick": {
          "summary": "v2.4 removed the onboarding discount",
          "confidence": 0.78,
          "nextStep": "Restore the intro offer for US and re-measure over 7 days",
          "openHypothesisId": null
        },
        "analystNotes": "ASA spend was flat throughout — paid traffic ruled out."
      }
    }
  }
}
```

Reports are cached (`cache_until`) — re-asking the same question inside the cache window returns the existing analysis instead of burning another run.