Retrieve a form's metricsMenu

Retrieve a form's metrics

GET/v1/forms/{id}/metrics

Requires an API key with the forms:read scope. About keys and scopes

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

idstringrequired

The form's id.

uuid

Query parameters

fromstringoptional: 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.
tostringoptional: 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-Workspacestringoptional

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.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with a FormMetrics in data. Otherwise returns an error; Errors lists every code and which to retry.

totalintegerrequired

All submissions.

min 0

createdintegerrequired

Submissions that created a contact.

min 0

updatedintegerrequired

Submissions that updated an existing contact.

min 0

honeypotintegerrequired

Submissions caught as bots by the honeypot field.

min 0

pendingintegerrequired

Double opt-in submissions still waiting for their confirmation link.

min 0

expiredintegerrequired

Double opt-in submissions whose link lapsed unconfirmed after 7 days.

min 0

viewsintegerrequired

Times the form was shown, each visitor counted once a day; crawlers and link previews are left out.

min 0

submitRatenumber | nullrequired

Submissions, less honeypot catches, per view; null before the first view.

min 0

byTrafficSourceobject[]required

Views and submissions by where visitors came from, most views first, at most 20.

3 child attributes

trafficSourcestringrequired

Where the visitor came from: the link's utm_source, else the referring site, else direct.

viewsintegerrequired

min 0

submissionsintegerrequired

Submissions, less honeypot catches.

min 0

byPlacementobject[]required

Views and submissions by how the form showed.

3 child attributes

placementstringrequired

Its own link, framed in a site, a popup, or unknown for submissions whose page did not say.

one of link, embed, popup, unknown

viewsintegerrequired

min 0

submissionsintegerrequired

Submissions, less honeypot catches.

min 0

windowReportWindowrequired

The window these figures cover.

3 child attributes

fromstringrequired

Start of the window, inclusive.

date-time

tostringrequired

End of the window, exclusive.

date-time

timezonestringrequired

The workspace timezone the date bounds are in.

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

const response = await fetch('https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "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"
    }
  }
}