# Retrieve a form's metrics

Source: https://kirora.io/docs/api/reference/getFormMetrics

`GET /v1/forms/{id}/metrics`

Requires an API key with the `forms:read` scope. [About keys and scopes](https://kirora.io/docs/api/reference/authentication)

Works with integration, agent and partner keys.

Returns a form's submissions by outcome, views and the submit rate over the window (the last 30 days unless `from` and `to` say otherwise), split by where visitors came from (`byTrafficSource`) and how the form showed (`byPlacement`).

## Path parameters

- `id` (string, required, uuid) — The form's id.

## Query parameters

- `from` (string, optional) — Start of the window, inclusive: a date-time, or a date meaning the start of that day in the workspace timezone. Give with `to`; omit both for the last 30 days. A date-time falls on a quarter hour, since views are counted per quarter hour.
- `to` (string, optional) — End of the window, exclusive, in the same forms. To include a whole last day, pass the day after it: `from=2026-10-01&to=2026-10-08` covers 1 to 7 October. No later than the end of today; a window touches at most 366 days. Give with `from`.

## Header parameters

- `Kirora-Workspace` (string, optional, pattern `^[A-Za-z0-9._:-]{1,128}$`) — Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

## Returns

Returns `200 OK` with a `FormMetrics` in `data`. Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `total` (integer, required, min 0) — All submissions.
- `created` (integer, required, min 0) — Submissions that created a contact.
- `updated` (integer, required, min 0) — Submissions that updated an existing contact.
- `honeypot` (integer, required, min 0) — Submissions caught as bots by the honeypot field.
- `pending` (integer, required, min 0) — Double opt-in submissions still waiting for their confirmation link.
- `expired` (integer, required, min 0) — Double opt-in submissions whose link lapsed unconfirmed after 7 days.
- `views` (integer, required, min 0) — Times the form was shown, each visitor counted once a day; crawlers and link previews are left out.
- `submitRate` (number | null, required, min 0) — Submissions, less honeypot catches, per view; `null` before the first view.
- `byTrafficSource` (object[], required) — Views and submissions by where visitors came from, most views first, at most 20.
  - `trafficSource` (string, required) — Where the visitor came from: the link's `utm_source`, else the referring site, else `direct`.
  - `views` (integer, required, min 0)
  - `submissions` (integer, required, min 0) — Submissions, less honeypot catches.
- `byPlacement` (object[], required) — Views and submissions by how the form showed.
  - `placement` (string, required, one of `link`, `embed`, `popup`, `unknown`) — Its own link, framed in a site, a popup, or `unknown` for submissions whose page did not say.
  - `views` (integer, required, min 0)
  - `submissions` (integer, required, min 0) — Submissions, less honeypot catches.
- `window` (ReportWindow, required) — The window these figures cover.
  - `from` (string, required, date-time) — Start of the window, inclusive.
  - `to` (string, required, date-time) — End of the window, exclusive.
  - `timezone` (string, required) — The workspace timezone the date bounds are in.

## Example

```bash
curl https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "total": 412,
    "created": 318,
    "updated": 61,
    "honeypot": 9,
    "pending": 24,
    "expired": 6,
    "views": 5120,
    "submitRate": 0.0787,
    "byTrafficSource": [
      {
        "trafficSource": "instagram",
        "views": 2900,
        "submissions": 251
      },
      {
        "trafficSource": "direct",
        "views": 1460,
        "submissions": 98
      },
      {
        "trafficSource": "acme-shop.com",
        "views": 760,
        "submissions": 54
      }
    ],
    "byPlacement": [
      {
        "placement": "link",
        "views": 3100,
        "submissions": 270
      },
      {
        "placement": "embed",
        "views": 2020,
        "submissions": 133
      }
    ],
    "window": {
      "from": "2026-09-07T23:00:00.000Z",
      "to": "2026-10-07T23:00:00.000Z",
      "timezone": "Europe/London"
    }
  }
}
```