# Goals

Source: https://docs.mirafive.io/rest-api/goals

> List a MIRA FIVE project's goals with conversions, people, rate and revenue for a period, and read one goal's report with its trend.

A goal is an action with a role: `purchase` (what buying is, at most one per project), `conversion` (another success, such as a sign-up) or `intent` (a sign someone wants to buy, such as viewing pricing). The goals endpoints report how often each was reached. Goals are defined in MIRA FIVE, or by an agent through the [MCP server](https://docs.mirafive.io/mcp/tools#create_goal).

## List goals

```text
GET /api/v1/projects/{project_id}/goals
```

The project's active goals in the order the Goals screen shows them, with their numbers for the period. Actions without a role are not listed. The list does not page.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `period` | string | `30d` | `1h`, `24h`, `7d`, `30d`, `90d`, `12m` or `custom`. See [Periods](https://docs.mirafive.io/rest-api#periods). |
| `from` | string | none | First day of a custom period, `YYYY-MM-DD`. **Required** with `period=custom`. |
| `to` | string | none | Last day of a custom period, inclusive. **Required** with `period=custom`. |

`compare` is refused. Filters are not read.

```bash
curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/goals \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'period=7d'
```

```json title="200 OK"
{
  "data": [
    {
      "id": "01948d2e-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "type": "goals",
      "attributes": {
        "name": "Order completed",
        "description": "Checkout finished and paid.",
        "role": "purchase",
        "revenueProperty": null,
        "conversions": 151,
        "people": 138,
        "rate": 0.0327,
        "revenue": [
          { "currency": "EUR", "amount": 9214.8 },
          { "currency": "CHF", "amount": 189 }
        ]
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/goals/01948d2e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
      }
    },
    {
      "id": "01948d2f-6a7b-7c8d-8e9f-0a1b2c3d4e5f",
      "type": "goals",
      "attributes": {
        "name": "Newsletter signup",
        "description": null,
        "role": "conversion",
        "revenueProperty": null,
        "conversions": 247,
        "people": 239,
        "rate": 0.0567,
        "revenue": []
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/goals/01948d2f-6a7b-7c8d-8e9f-0a1b2c3d4e5f"
      }
    },
    {
      "id": "01948d30-7b8c-7d9e-9f0a-1b2c3d4e5f6a",
      "type": "goals",
      "attributes": {
        "name": "Started checkout",
        "description": null,
        "role": "intent",
        "revenueProperty": null,
        "conversions": 402,
        "people": 356,
        "rate": 0.0844,
        "revenue": []
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/goals/01948d30-7b8c-7d9e-9f0a-1b2c3d4e5f6a"
      }
    }
  ],
  "meta": {
    "period": {
      "preset": "7d",
      "from": "2026-09-21T00:00:00+02:00",
      "to": "2026-09-28T00:00:00+02:00",
      "timezone": "Europe/Berlin",
      "interval": "day",
      "comparison": null,
      "clampedToRetention": false
    },
    "active": 4218,
    "visits": 6630,
    "perVisit": false,
    "coverage": 0.62
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The goal's id. Use it for [Get a goal report](#get-a-goal-report), the [funnel](https://docs.mirafive.io/rest-api/funnel) and the `goal` [person filter](https://docs.mirafive.io/rest-api/people#person-filters). |
| `attributes.name` | string | The goal's name. |
| `attributes.description` | string or null | Its description. |
| `attributes.role` | string | `purchase`, `conversion` or `intent`. |
| `attributes.revenueProperty` | string or null | The event property its events carry their amount in when they send no `revenue`, e.g. `value`. |
| `attributes.conversions` | integer | Every event that reached it in the period, with consent or without. |
| `attributes.people` | integer | People who reached it. |
| `attributes.rate` | number or null | People who reached it over people active (`meta.active`), 0–1. On a consentless project, conversions over visits. |
| `attributes.revenue` | array | Revenue per currency, `{ currency, amount }`, reporting currency first. |
| `links.self` | string | The goal's report. |
| `meta.active` | integer | People active in the period. |
| `meta.visits` | integer | Visits in the period. |
| `meta.perVisit` | boolean | `true` on a project without consented traffic: rates are per visit, and `people` counts nobody. |
| `meta.coverage` | number or null | Share (0–1) of pageviews collected with consent, which people counts rest on. |

## Get a goal report

```text
GET /api/v1/projects/{project_id}/goals/{goal_id}
```

One goal over the period, with its trend. An action without a role gets `404`.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `period` | string | `30d` | `1h`, `24h`, `7d`, `30d`, `90d`, `12m` or `custom`. See [Periods](https://docs.mirafive.io/rest-api#periods). |
| `from` | string | none | First day of a custom period, `YYYY-MM-DD`. **Required** with `period=custom`. |
| `to` | string | none | Last day of a custom period, inclusive. **Required** with `period=custom`. |
| `compare` | string | none | `previous` fills `previous` and the trends' `comparison` with the period before. |

```bash
curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/goals/01948d2e-5f6a-7b8c-9d0e-1f2a3b4c5d6e \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'period=7d' \
  --data-urlencode 'compare=previous'
```

```json title="200 OK"
{
  "data": {
    "id": "01948d2e-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "type": "goal-reports",
    "attributes": {
      "name": "Order completed",
      "role": "purchase",
      "archived": false,
      "conversions": 151,
      "people": 138,
      "active": 4218,
      "visits": 6630,
      "perVisit": false,
      "rate": 0.0327,
      "revenue": [
        { "currency": "EUR", "amount": 9214.8 },
        { "currency": "CHF", "amount": 189 }
      ],
      "coverage": 0.62,
      "previous": { "conversions": 133, "people": 121, "rate": 0.0305 },
      "trend": {
        "conversions": {
          "interval": "day",
          "timezone": "Europe/Berlin",
          "format": "number",
          "currency": null,
          "series": [
            {
              "key": "conversions",
              "points": [
                { "t": "2026-09-21T00:00:00+02:00", "v": 22 },
                { "t": "2026-09-22T00:00:00+02:00", "v": 19 },
                { "t": "2026-09-23T00:00:00+02:00", "v": 25 },
                { "t": "2026-09-24T00:00:00+02:00", "v": 21 },
                { "t": "2026-09-25T00:00:00+02:00", "v": 18 },
                { "t": "2026-09-26T00:00:00+02:00", "v": 31 },
                { "t": "2026-09-27T00:00:00+02:00", "v": 15 }
              ]
            }
          ],
          "comparison": [
            {
              "key": "conversions",
              "points": [
                { "t": "2026-09-14T00:00:00+02:00", "v": 17 },
                { "t": "2026-09-15T00:00:00+02:00", "v": 20 },
                { "t": "2026-09-16T00:00:00+02:00", "v": 18 },
                { "t": "2026-09-17T00:00:00+02:00", "v": 21 },
                { "t": "2026-09-18T00:00:00+02:00", "v": 16 },
                { "t": "2026-09-19T00:00:00+02:00", "v": 24 },
                { "t": "2026-09-20T00:00:00+02:00", "v": 17 }
              ]
            }
          ]
        },
        "people": {
          "interval": "day",
          "timezone": "Europe/Berlin",
          "format": "number",
          "currency": null,
          "series": [{ "key": "people", "points": [{ "t": "2026-09-21T00:00:00+02:00", "v": 20 }] }],
          "comparison": [{ "key": "people", "points": [{ "t": "2026-09-14T00:00:00+02:00", "v": 16 }] }]
        },
        "rate": {
          "interval": "day",
          "timezone": "Europe/Berlin",
          "format": "percent",
          "currency": null,
          "series": [{ "key": "rate", "points": [{ "t": "2026-09-21T00:00:00+02:00", "v": 0.0283 }] }],
          "comparison": [{ "key": "rate", "points": [{ "t": "2026-09-14T00:00:00+02:00", "v": 0.0251 }] }]
        }
      }
    },
    "links": {
      "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/goals/01948d2e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
    }
  },
  "meta": {
    "period": {
      "preset": "7d",
      "from": "2026-09-21T00:00:00+02:00",
      "to": "2026-09-28T00:00:00+02:00",
      "timezone": "Europe/Berlin",
      "interval": "day",
      "comparison": {
        "from": "2026-09-14T00:00:00+02:00",
        "to": "2026-09-21T00:00:00+02:00"
      },
      "clampedToRetention": false
    }
  }
}
```

The `people` and `rate` trends are shortened here to their first point. Each has one point per bucket, like `conversions`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The goal's id. |
| `attributes.name`, `attributes.role` | string | As in [List goals](#list-goals). |
| `attributes.archived` | boolean | Whether the goal is archived. |
| `attributes.conversions` | integer | Events that reached it in the period. |
| `attributes.people` | integer | People who reached it. |
| `attributes.active` | integer | People active in the period. |
| `attributes.visits` | integer | Visits in the period. |
| `attributes.perVisit` | boolean | `true` on a consentless project: `rate` is conversions over visits. |
| `attributes.rate` | number or null | `people` over `active` (or `conversions` over `visits` when `perVisit`), 0–1. |
| `attributes.revenue` | array | Revenue per currency, `{ currency, amount }`. |
| `attributes.coverage` | number or null | Share (0–1) of pageviews collected with consent. |
| `attributes.previous` | object or null | `conversions`, `people` and `rate` of the previous period. `null` without `compare=previous`, or when that period is outside the history. |
| `attributes.trend.conversions`, `attributes.trend.people`, `attributes.trend.rate` | object | One trend each, shaped like the [overview's trend](https://docs.mirafive.io/rest-api/overview#get-the-overview): `interval`, `timezone`, `format`, `currency`, `series`, `comparison`. |
| `meta.period` | object | The window read. See [Periods](https://docs.mirafive.io/rest-api#periods). |