Report usage

Planned protocol reference. Usage records, reconciliation, statements and payment recording are not served by the current Talent API sandbox. The examples below cannot yet be run against it. Start with the runnable quickstart and sandbox support matrix.

Licenses that pay the talent per output, per second or per impression are settled from the usage you report. Reflections reconciles your reports against its own record of checks and generations, and issues a monthly statement per license. Reflections never moves money; the licensee pays the talent’s payee and records the payment.

Know what to report

A usage_report obligation on a check, generation or session says which unit to report and how soon:

{ "type": "usage_report", "units": "seconds", "within": "P1D" }

Report each subject within within, counted from the generation’s decision or the session’s end. Each record names one subject: the generation (gen_…) or session (ses_…) it settles.

`units`	Report	Typical subject
`outputs`	Delivered outputs, usually `1` per generation	Generation
`seconds`	Seconds of generated audio or video, or of a live session	Generation or session
`characters`	Characters of generated text or of a speech script	Generation
`placements`	Places the output was published, with `placement`	Generation
`impressions`	Times the output was shown, with `placement`	Generation

The account that knows the number reports it. The platform reports outputs, seconds and characters. Placements and impressions are usually known to the licensee, who reports them, or the platform does when it publishes for the licensee. Send Reflections-Account when you report for a connected licensee. A record counts against one license. When a generation or session was decided under several licenses, as with two talent in one output, send one record per license and set license on each. With one license, license is optional.

Send a batch

Send up to 1,000 records per call to POST /v1/usage_records. Give each batch its own Idempotency-Key, derived from your batch ID, so a retry never counts twice.

curl https://app.reflections.ai/v1/usage_records \
  -H "Authorization: Bearer rk_test_…" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: usage-batch-2026-10-17T18" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "subject": "ses_q8v1m3n7p4r6s9t0wxyhk5zba2", "units": "seconds", "quantity": 412, "occurred_at": "2026-10-17T18:07:00Z" },
      { "subject": "gen_2q8v1m3n7p4r6s9t0wxyhk5zba", "units": "seconds", "quantity": 3.4, "occurred_at": "2026-10-17T18:06:03Z" },
      {
        "subject": "gen_6s9t0wxyhk5zba2q8v1m3n7p4r",
        "units": "placements",
        "quantity": 1,
        "occurred_at": "2026-10-17T19:00:00Z",
        "placement": { "channel": "social", "territory": "US", "url": "https://social.example.com/ridgeline/posts/1182" }
      }
    ]
  }'

type UsageItem = {
  subject: string; // gen_… or ses_…
  units: string;
  quantity: number;
  occurredAt: string;
  placement?: { channel: string; territory: string; url?: string };
};

// One batch from your usage store. Its ID never changes, so a retry reuses the key.
export async function reportUsage(batch: { id: string; items: UsageItem[] }) {
  const res = await fetch("https://app.reflections.ai/v1/usage_records", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
      "Reflections-Version": "2026-10-15",
      "Idempotency-Key": `usage-batch-${batch.id}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      records: batch.items.map((item) => ({
        subject: item.subject,
        units: item.units,
        quantity: item.quantity,
        occurred_at: item.occurredAt,
        ...(item.placement ? { placement: item.placement } : {}),
      })),
    }),
  });
  if (!res.ok) throw new Error(`Report usage failed: ${res.status}`); // retry with the same key
  const result = await res.json();
  return result.data.filter((r: { status: string }) => r.status === "rejected");
}

import os, requests

def report_usage(batch):
    """batch: one batch from your usage store. Its ID never changes, so a retry reuses the key."""
    res = requests.post(
        "https://app.reflections.ai/v1/usage_records",
        headers={
            "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
            "Reflections-Version": "2026-10-15",
            "Idempotency-Key": f"usage-batch-{batch.id}",
        },
        json={
            "records": [
                {
                    "subject": item.subject,  # gen_… or ses_…
                    "units": item.units,
                    "quantity": item.quantity,
                    "occurred_at": item.occurred_at,
                    **({"placement": item.placement} if item.placement else {}),
                }
                for item in batch.items
            ]
        },
    )
    res.raise_for_status()  # retry with the same key
    return [r for r in res.json()["data"] if r["status"] == "rejected"]

rejected = [r for r in result["data"] if r["status"] == "rejected"]

Each record is accepted or rejected on its own. The response lists them in the order you sent:

{
  "object": "list",
  "data": [
    {
      "id": "ur_6a8c0e2g4j6m8p0r2t4w6y8b0d",
      "object": "usage_record",
      "subject": "ses_q8v1m3n7p4r6s9t0wxyhk5zba2",
      "units": "seconds",
      "quantity": 412,
      "occurred_at": "2026-10-17T18:07:00Z",
      "status": "accepted",
      "rejection": null,
      "license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
      "statement": "stmt_3d5f7h9k1m3p5r7t9w1y3a5c7e"
    },
    {
      "id": "ur_8c0e2g4j6m8p0r2t4w6y8b0d2f",
      "object": "usage_record",
      "subject": "gen_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "units": "seconds",
      "quantity": 3.4,
      "status": "rejected",
      "rejection": { "code": "duplicate", "detail": "ur_4y6a8c0e2g4j6m8p0r2t4w6y8b already reports this generation in seconds." },
      "license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
      "statement": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Handle rejections

`rejection.code`	Meaning	What to do
`unknown_subject`	The ID is not a generation or session of yours, or of the licensee you named.	Check the ID and the `Reflections-Account` header.
`exceeds_observed`	More units than Reflections recorded, such as more seconds than the session ran.	Report what you measured from the output.
`outside_scope`	The placement’s channel or territory is outside the license.	Do not retry. Remove the placement, and tell the licensee.
`duplicate`	This subject, license and unit are already reported.	Nothing, unless the first record was wrong; then correct it.
`period_closed`	The statement for that period is already issued.	Contact support with the record IDs.

An outside_scope placement means the output was used where the license does not cover it. The rejection does not undo the placement; take it down.

Correct a record

Records never change. To fix one, send a new record with correction_of set to the record it replaces. The new record replaces the old one in reconciliation.

{
  "records": [
    {
      "subject": "ses_q8v1m3n7p4r6s9t0wxyhk5zba2",
      "units": "seconds",
      "quantity": 398,
      "occurred_at": "2026-10-17T18:07:00Z",
      "correction_of": "ur_6a8c0e2g4j6m8p0r2t4w6y8b0d"
    }
  ]
}

Reconciliation and statements

Reflections records what it observed: every allowed generation, every session’s duration, every script’s length. Each statement line shows reported (yours), observed (Reflections’) and billable, the greater of the two. Under-reporting is visible without trusting either side.

{
  "id": "stmt_3d5f7h9k1m3p5r7t9w1y3a5c7e",
  "object": "statement",
  "license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
  "status": "issued",
  "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-11-01T00:00:00Z" },
  "currency": "usd",
  "lines": [
    {
      "description": "Speaking voice, live sessions",
      "units": "seconds",
      "reported": 182400,
      "observed": 183150,
      "billable": 183150,
      "rate": { "amount": 2, "currency": "usd" },
      "amount": 366300
    }
  ],
  "amount_due": 366300,
  "amount_paid": 0,
  "reconciliation": { "result": "under_reported", "detail": "750 seconds observed and not reported." }
}

reconciliation.result is matched, under_reported or over_reported. When a statement is final for the month, the licensee receives statement.issued. The licensee pays the talent’s payee directly, then records it with POST /v1/statements/{statement_id}/payments. The statement becomes paid when confirmed payments reach amount_due, or disputed if the talent’s side disputes it. Daily test statements are a proposed test capability. The current sandbox does not generate statements or accept usage records.

What can go wrong

Problem	What to do
A batch call times out	Retry with the same `Idempotency-Key`. A new key would send every record again, and duplicates are rejected one by one.
`422 idempotency_key_reused`	You changed the batch and kept its key. A changed batch is a new batch.
You missed `within`	Report as soon as you can. The deadline is part of the license you are using.

Reported usage, statements and payments are kept for 7 years, so the talent and their representatives can audit every license.

Usage and settlement

Usage records, reconciliation, statements and audit.

The endpoint reference.

Brands and agencies

Reading statements and recording payments.

Real-time sessions

Ending a session and reporting its seconds.

Get started

Quickstarts

Concepts

Integration guides

Build

Go to production

Report usage

Know what to report

Send a batch

Handle rejections

Correct a record

Reconciliation and statements

What can go wrong

Usage and settlement

Report usage

Brands and agencies

Real-time sessions

​Know what to report

​Send a batch

​Handle rejections

​Correct a record

​Reconciliation and statements

​What can go wrong

​Related

Usage and settlement

Report usage

Brands and agencies

Real-time sessions

Know what to report

Send a batch

Handle rejections

Correct a record

Reconciliation and statements

What can go wrong

Related