Retrieve a list's usageMenu

Retrieve a list's usage

GET/v1/lists/{id}/usage

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

Works with integration, agent and partner keys.

Returns what names the list: campaigns whose audience, rules or exclusions name it, or whose content has a block shown only to, or hidden from, its members, forms that add people to it, goals whose rules name it, journeys whose rules or steps name it, segments whose rules name it, and templates (the draft or the published version) and shared blocks with such a block, up to 50 of each (hasMore when a kind holds more). Deleting the list is refused (409 IN_USE) while any of them is a campaign not yet sent or cancelled (draft, scheduled, testing for an A/B test, or sending), a published form not archived, a goal not retired, an active or paused journey, a segment, a template or a shared block. Draft or archived forms, sent or cancelled campaigns, retired goals and draft or ended journeys do not block it.

Path parameters

idstringrequired

The list's id.

uuid

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 ListUsage in data. Otherwise returns an error; Errors lists every code and which to retry.

campaignsobject[]required

3 child attributes

idstringrequired: uuid
namestringrequired
statusstringrequired: one of draft, scheduled, sending, testing, sent, cancelled

formsobject[]required

2 child attributes

idstringrequired: uuid
namestringrequired

goalsobject[]required

2 child attributes

idstringrequired: uuid
namestringrequired

journeysobject[]required

3 child attributes

idstringrequired: uuid
namestringrequired
statusstringrequired: one of draft, active, paused, ended

segmentsobject[]required

2 child attributes

idstringrequired: uuid
namestringrequired

templatesobject[]required

2 child attributes

idstringrequired: uuid
namestringrequired

sharedBlocksobject[]required

2 child attributes

idstringrequired: uuid
namestringrequired

hasMorebooleanrequired

More use it than are listed: each list stops at 50.

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

const response = await fetch('https://api.kirora.io/v1/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage', {
  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/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage",
    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/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage", 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/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage");
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": {
    "campaigns": [
      {
        "id": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
        "name": "October newsletter",
        "status": "scheduled"
      }
    ],
    "forms": [
      {
        "id": "0192f3f1-2b3c-7d4e-9f50-6b7c8d9e0f12",
        "name": "Newsletter sign-up"
      }
    ],
    "goals": [],
    "journeys": [],
    "segments": [],
    "templates": [],
    "sharedBlocks": [],
    "hasMore": false
  }
}