> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/2020-05-18/reports-cookbook/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Reports Cookbook

> Follow API recipes for running Persona Reports and retrieving their results.

This doc provides recipes for running reports via API. Note that reports can also be run [from the Persona dashboard](https://withpersona.com/dashboard/reports).

> **Info**
>
> Learn more in the [Reports API documentation](/api-reference/reports)

## Run your first report

Create your first report by creating a POST request to the reports resource:

**`curl`**

```curl curl
API_KEY=YOUR_API_KEY_HERE
curl -X POST -H 'Content-Type: application/json' \
	-H "Authorization: Bearer $API_KEY" -d'{
  "data": {
    "attributes": {
      "report-template-id": YOUR_TEMPLATE_ID,
    }
  }
}' https://withpersona.com/api/v1/reports
```

After you submit the request, your report is processed as soon as possible. This usually happens within a second.

The HTTP response will include a **report ID** that you can use to poll for the report result:

**`json`**

```json json
{
  "data": {
    "type": "report/watchlist",
    "id": "rep_yourfirstreportid",
    "attributes": {
       "status": "pending",
       "..." : "..."
    }
  }
}
```

## Get the results of a report

Fetch the results of a report using the **report ID**:

**`curl`**

```curl curl
API_KEY=YOUR_API_KEY_HERE
curl -X GET -H 'Content-Type: application/json' \
	-H "Authorization: Bearer $API_KEY" \
  https://withpersona.com/api/v1/reports/YOUR_REPORT_ID_HERE
```

Once the report `status` is `ready`, the results will be available in the response:

**`json`**

```json json
{
  "data": {
    "type: "report/watchlist",
    "id": "rep_yourfirstreportid",
    "attributes": {
       "status": "ready",
      ...
    }
  }
}
```

> Follow API recipes for running Persona Reports and retrieving their results.