Reports

Report a conversion funnel over events

POST/v1/reports/funnel

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

How many contacts did each event in order. A contact enters with the first step's earliest event in the window (calendar days in the workspace timezone, default the last 30), and reaches a later step with an event after the previous step's, within withinDays of entering. Each contact counts once per step, however many times they repeat it. Events past retention are no longer held.

Request body

startDatestringoptional

First day, inclusive, in the workspace timezone. Give with endDate.

date

endDatestringoptional

Last day, inclusive, no later than today. Give with startDate; a window is at most 366 days. Omit both for the last 30 days.

date

stepsobject[]required

The events, in order.

at least 2 items · at most 5 items

2 child attributes

eventNamestringrequired

The event that completes the step.

1–128 characters

whereobject[]optional

Every condition must hold for an event to count as this step.

at least 1 item · at most 5 items

3 child attributes

propertystringrequired

The event property key.

1–64 characters

operatorstringrequired

one of equals, notEquals, gt, gte, lt, lte

valuestring | number | booleanrequired

withinDaysintegeroptional

How long after the first step a contact has to finish the rest.

min 1 · max 90 · default 7

Returns

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

timezonestringrequired

The workspace timezone the dates are calendar days in.

startDatestringrequired

First day of the window (inclusive).

date

endDatestringrequired

Last day of the window (inclusive).

date

withinDaysintegerrequired

The window each contact had to finish in.

min -9007199254740991 · max 9007199254740991

stepsobject[]required

5 child attributes

eventNamestringrequired

contactsintegerrequired

Contacts who reached this step, in order, within withinDays of the first.

min 0 · max 9007199254740991

conversionRatenumber | nullrequired

Fraction of those who started; null when nobody did.

min 0

stepRatenumber | nullrequired

Fraction of those who reached the step before; null for the first, or when nobody did.

min 0

dropOffintegerrequired

Contacts who reached the step before but not this one; 0 for the first.

min 0 · max 9007199254740991

curl -X POST https://api.kirora.io/v1/reports/funnel \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {
        "eventName": "Order Completed"
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/reports/funnel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "steps": [
      {
        "eventName": "Order Completed"
      }
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/reports/funnel",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "steps": [
            {
                "eventName": "Order Completed",
            },
        ],
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "steps": [
	    {
	      "eventName": "Order Completed"
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/reports/funnel", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

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

Response · 200

{
  "data": {
    "timezone": "Europe/London",
    "startDate": "2030-03-14",
    "endDate": "2030-03-14",
    "withinDays": -9007199254740991,
    "steps": [
      {
        "eventName": "Order Completed",
        "contacts": 0,
        "conversionRate": 0,
        "stepRate": 0,
        "dropOff": 0
      }
    ]
  }
}

Example values are generated from the schema.