Export Usage and Workspace Events

Page through your organization's Kimchi LLM usage records and workspace events into your own warehouse or reporting job, with cursor-based resumption, retry handling, and per-attempt tagging.

This guide explains how to copy your organization's Kimchi LLM usage records and workspace events into your own systems. Examples include a data warehouse or a reporting job. Read the records page by page, oldest first. Store a cursor so the next run continues where the last one stopped.

Use this when you need a full export into your own warehouse, a continuous replication job, or a billing reconciliation. For day-to-day inspection in the console, see the Usage and Analytics pages.

Before you start

Before you export events, ensure you have:

  • A Cast AI API key whose role includes read access to LLM requests (permission aiOptimizer.llmRequests.read).
  • Your organization ID.
  • A way to store the cursor between runs so the next call picks up where the last one stopped.
  • A way to store records by id and replace older versions. A record can come back with the same id and a newer recorded_at.

The endpoint also accepts X-API-Key for organizations that use header-based auth. The same key works against https://api.cast.ai (US) or https://api.eu.cast.ai (EU). An enterprise parent organization reading a child organization must also send the X-CastAi-Organization-Id header with the child organization ID.

Understand the record envelope

Every record carries the same five envelope fields, plus one block named after its type:

FieldDescription
idStable record ID. A corrected record keeps its ID.
typellm_usage or workspace_event.
occurred_atWhen the event happened.
recorded_atRecording time for this version of the record. Event ordering follows this value.
schema_versionVersion of the type's block. Currently 1 for both types.

The llm_usage block carries one record per LLM request attempt, with OpenTelemetry GenAI field names where one exists. The workspace_event block carries lifecycle events for Kimchi workspaces. Full field tables live on the List Kimchi Events reference page.

Export records with cursor pagination

The export is a loop. Call without a cursor, save the records, call again with nextPageCursor, and stop when hasMore is false. Store the last nextPageCursor so the next run starts from it and pulls only new records.

Make the first call without a cursor

The API returns your oldest records first, starting at the oldest record of the last 90 days. Older records do not export. To start from a specific date, pass startTime on this first call.

curl -s -H "X-API-Key: $CASTAI_API_KEY" \
  "https://api.cast.ai/ai-optimizer/v1beta/organizations/$ORG_ID/events?type=llm_usage&pageSize=1000"

To start from a date, for example five days back:

curl -s -H "X-API-Key: $CASTAI_API_KEY" \
  "https://api.cast.ai/ai-optimizer/v1beta/organizations/$ORG_ID/events?type=llm_usage&pageSize=1000&startTime=2026-11-06T00:00:00Z"

Kimchi treats a startTime more than 90 days back as 90 days back. A startTime in the future, or within the last two minutes, returns an empty page with hasMore: false and a nextPageCursor that starts at that date. Call again later with that cursor to pick up records as they appear.

Save each record by its id

Each record has a stable id. A corrected or re-delivered record returns with the same id and a newer recorded_at. Insert new records by id; replace existing ones. The stored version stays the latest.

Call again with nextPageCursor until hasMore is false

Send nextPageCursor from the previous response back as the cursor query parameter. Keep going while hasMore is true.

curl -s -H "X-API-Key: $CASTAI_API_KEY" \
  "https://api.cast.ai/ai-optimizer/v1beta/organizations/$ORG_ID/events?type=llm_usage&pageSize=1000&cursor=$CURSOR"

A page covers at most one hour of recording time, so a page can have fewer records than pageSize, or none, while hasMore stays true. Do not stop on an empty page; only hasMore: false ends the run.

Store nextPageCursor for the next run

When hasMore is false, save nextPageCursor. On the next run, start from it to get only new records. Records become available about two minutes after Kimchi records them. The cursor always sits a little behind real time.

📘

Keep one cursor per type. A cursor for llm_usage does not advance workspace_event, and the two types share no ordering.

Handle retries and errors

The endpoint allows about one request per second per organization, with short bursts allowed. All keys of the organization share the limit, so concurrent jobs step on each other.

StatusMeaning
400Invalid type, pageSize, cursor or startTime. Fix the request before retrying.
401The API key is missing or invalid.
403The key lacks the required permission, or the organization is not yours.
429Too many requests. Wait the number of seconds in the Retry-After header, or 1 second if it is missing, then send the same request again.
503Data is briefly behind. Wait the seconds in the Retry-After header, or 10 seconds if it is missing, then retry with the same cursor.

A retried request uses the same cursor, so pages do not duplicate on retry. The reference exporter handles 429 and 503 automatically.

Tag requests to attribute spend

Attach tags to a Kimchi gateway request; the matching usage record then carries them under kimchi.tags. Use tags to attribute spend to a person, project, or environment. The export then groups cost by any dimension your organization tracks.

curl -s https://llm.kimchi.dev/openai/v1/chat/completions \
  -H "Authorization: Bearer $KIMCHI_API_KEY" \
  -H "X-Tags: user:[email protected],project:checkout" \
  -d '{ ... }'

A tag follows key:value format. The key and the value must each start and end with a letter or digit. They can otherwise contain letters, digits, ., _, -, and @. The gateway accepts @ only inside a value, not in a key or at a value's start or end. A request can have up to 10 tags, with up to 64 characters in each key and value. A request with an invalid tag gets a 400 response with a message describing the problem.

Use consistent tags to group requests by a dimension such as user:[email protected] or project:checkout. You can select these dimensions in Usage → By tag or in the API's cost breakdown. Tags do not change native owner or team attribution. When several people share one key, its owner remains the native owner for those requests. Use distinct user-owned keys when you need native per-person attribution. See Tags and Usage attribution for the full rules.

Join usage and workspace events

A single client request that retries on another model or provider has one record per attempt. To count requests, count distinct kimchi.request_group_id. To sum cost, sum every record.

llm_usage records and workspace_event records join on kimchi.workspace_id. A workspace event's kimchi.workspace_id matches the same field in llm_usage. Load both types and answer questions like "which requests ran inside this workspace?" or "what happened to the workspace at the moment this failure occurred?". Use kimchi.workspace_uuid to join into Cast AI's workspace APIs.

Reference exporter in Python

import time
import requests

BASE = "https://api.cast.ai/ai-optimizer/v1beta/organizations/{org}/events"

def export(org_id, api_key, event_type, cursor=""):
    while True:
        resp = requests.get(
            BASE.format(org=org_id),
            headers={"X-API-Key": api_key},
            params={"type": event_type, "pageSize": 1000, "cursor": cursor},
            timeout=60,
        )
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 1)))
            continue
        if resp.status_code == 503:
            time.sleep(int(resp.headers.get("Retry-After", 10)))
            continue
        resp.raise_for_status()
        page = resp.json()
        for record in page.get("items", []):
            save_by_id(record)  # insert, or replace the record with the same id
        cursor = page["nextPageCursor"]
        if not page.get("hasMore"):
            return cursor  # store it and pass it on the next run
        time.sleep(1)

The save_by_id step is the only piece the export leaves to your system. Write to a database table keyed by id, append to a parquet file in object storage, or stream into a warehouse. The API contract stays the same.

Next steps



Did this page help you?