cURL
# Set a unique key once per new action; persist it and reuse it for every retry.
: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"
: "${REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY:?Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example}"
curl --fail-with-body --max-time 30 -X POST 'https://app.reflections.ai/v1/usage_records' \
-H "Authorization: Bearer $REFLECTIONS_KEY" \
-H "Reflections-Version: 2026-10-15" \
-H "Idempotency-Key: $REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"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"
}
]
}'import { env, exit } from "node:process";
// Set a unique key once per new action; persist it and reuse it for every retry.
const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");
const idempotencyKey = env.REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example");
const response = await fetch("https://app.reflections.ai/v1/usage_records", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Reflections-Version": "2026-10-15",
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
},
body: JSON.stringify({
"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"
}
]
}),
signal: AbortSignal.timeout(30_000),
});
const responseBody = await response.text();
if (!response.ok) {
console.error(`HTTP ${response.status}: ${responseBody}`);
exit(1);
}
console.log(responseBody);
import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen
# Set a unique key once per new action; persist it and reuse it for every retry.
apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
raise ValueError("Set REFLECTIONS_KEY before running this example")
idempotencyKey = os.environ["REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY"]
if not idempotencyKey:
raise ValueError("Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example")
headers = {
"Authorization": f"Bearer {apiKey}",
"Reflections-Version": "2026-10-15",
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
}
data = json.dumps({
"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",
},
],
}).encode("utf-8")
request = Request("https://app.reflections.ai/v1/usage_records",
method="POST", headers=headers, data=data)
try:
with urlopen(request, timeout=30) as response:
print(response.read().decode("utf-8"))
except HTTPError as error:
error_body = error.read().decode("utf-8")
raise RuntimeError(f"HTTP {error.code}: {error_body}") from error
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
"time"
)
func main() {
// Set a unique key once per new action; persist it and reuse it for every retry.
apiKey := os.Getenv("REFLECTIONS_KEY")
if apiKey == "" {
panic("Set REFLECTIONS_KEY before running this example")
}
idempotencyKey := os.Getenv("REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY")
if idempotencyKey == "" {
panic("Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example")
}
body := strings.NewReader(`{
"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"
}
]
}`)
request, err := http.NewRequest("POST", "https://app.reflections.ai/v1/usage_records", body)
if err != nil {
panic(err)
}
request.Header.Set("Authorization", "Bearer " + apiKey)
request.Header.Set("Reflections-Version", "2026-10-15")
request.Header.Set("Idempotency-Key", idempotencyKey)
request.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 30 * time.Second}
response, err := client.Do(request)
if err != nil {
panic(err)
}
defer response.Body.Close()
responseBody, err := io.ReadAll(response.Body)
if err != nil {
panic(err)
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody))
}
fmt.Print(string(responseBody))
}
{
"object": "list",
"data": [
{
"id": "ur_6a8c0e2g4j6m8p0r2t4w6y8b0d",
"object": "usage_record",
"livemode": true,
"subject": "ses_q8v1m3n7p4r6s9t0wxyhk5zba2",
"units": "seconds",
"quantity": 412,
"occurred_at": "2026-10-17T18:07:00Z",
"status": "accepted",
"rejection": null,
"license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
"statement": "stmt_3d5f7h9k1m3p5r7t9w1y3a5c7e",
"created_at": "2026-10-17T19:00:04Z"
},
{
"id": "ur_8c0e2g4j6m8p0r2t4w6y8b0d2f",
"object": "usage_record",
"livemode": true,
"subject": "gen_2q8v1m3n7p4r6s9t0wxyhk5zba",
"units": "seconds",
"quantity": 3.4,
"occurred_at": "2026-10-17T18:06:03Z",
"status": "rejected",
"rejection": {
"code": "duplicate",
"detail": "ur_4y6a8c0e2g4j6m8p0r2t4w6y8b already reports this generation in seconds."
},
"license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
"statement": null,
"created_at": "2026-10-17T19:00:04Z"
}
],
"has_more": false,
"next_cursor": null
}{
"type": "https://docs.reflections.ai/errors/parameter_invalid",
"title": "A parameter is invalid",
"status": 400,
"code": "parameter_invalid",
"param": "use.territories[1]",
"detail": "\"UK\" is not an ISO 3166-1 alpha-2 code. Use \"GB\".",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/invalid_api_key",
"title": "The API key is not valid",
"status": 401,
"code": "invalid_api_key",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/account_not_connected",
"title": "The licensee has not connected your platform",
"status": 403,
"code": "account_not_connected",
"detail": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba has no active connection with your account.",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/idempotency_key_in_use",
"title": "A request with this key is still running",
"status": 409,
"code": "idempotency_key_in_use",
"detail": "Retry with the same key after a short wait.",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/idempotency_key_reused",
"title": "This key was used for a different request",
"status": 422,
"code": "idempotency_key_reused",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/rate_limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "invalid_request",
"request_id": "<string>",
"detail": "<string>",
"param": "<string>",
"doc_url": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "invalid_request",
"request_id": "<string>",
"detail": "<string>",
"param": "<string>",
"doc_url": "<string>"
}Usage records
Report usage
Planned contract — unavailable in test and live modes. This operation is a protocol reference, not a callable endpoint. Start with the working sandbox quickstart.
Reports usage for up to 1,000 generations or sessions in one call. Each record names what it
settles. Records are reconciled against Reflections’ own record of checks and generations;
a record that names an unknown subject or exceeds what was observed is rejected with a
reason. Send corrections as new records with correction_of.
Restricted keys need usage:write.
POST
/
usage_records
cURL
# Set a unique key once per new action; persist it and reuse it for every retry.
: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"
: "${REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY:?Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example}"
curl --fail-with-body --max-time 30 -X POST 'https://app.reflections.ai/v1/usage_records' \
-H "Authorization: Bearer $REFLECTIONS_KEY" \
-H "Reflections-Version: 2026-10-15" \
-H "Idempotency-Key: $REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"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"
}
]
}'import { env, exit } from "node:process";
// Set a unique key once per new action; persist it and reuse it for every retry.
const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");
const idempotencyKey = env.REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example");
const response = await fetch("https://app.reflections.ai/v1/usage_records", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Reflections-Version": "2026-10-15",
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
},
body: JSON.stringify({
"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"
}
]
}),
signal: AbortSignal.timeout(30_000),
});
const responseBody = await response.text();
if (!response.ok) {
console.error(`HTTP ${response.status}: ${responseBody}`);
exit(1);
}
console.log(responseBody);
import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen
# Set a unique key once per new action; persist it and reuse it for every retry.
apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
raise ValueError("Set REFLECTIONS_KEY before running this example")
idempotencyKey = os.environ["REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY"]
if not idempotencyKey:
raise ValueError("Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example")
headers = {
"Authorization": f"Bearer {apiKey}",
"Reflections-Version": "2026-10-15",
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
}
data = json.dumps({
"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",
},
],
}).encode("utf-8")
request = Request("https://app.reflections.ai/v1/usage_records",
method="POST", headers=headers, data=data)
try:
with urlopen(request, timeout=30) as response:
print(response.read().decode("utf-8"))
except HTTPError as error:
error_body = error.read().decode("utf-8")
raise RuntimeError(f"HTTP {error.code}: {error_body}") from error
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
"time"
)
func main() {
// Set a unique key once per new action; persist it and reuse it for every retry.
apiKey := os.Getenv("REFLECTIONS_KEY")
if apiKey == "" {
panic("Set REFLECTIONS_KEY before running this example")
}
idempotencyKey := os.Getenv("REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY")
if idempotencyKey == "" {
panic("Set REFLECTIONS_CREATE_USAGE_RECORDS_IDEMPOTENCY_KEY before running this example")
}
body := strings.NewReader(`{
"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"
}
]
}`)
request, err := http.NewRequest("POST", "https://app.reflections.ai/v1/usage_records", body)
if err != nil {
panic(err)
}
request.Header.Set("Authorization", "Bearer " + apiKey)
request.Header.Set("Reflections-Version", "2026-10-15")
request.Header.Set("Idempotency-Key", idempotencyKey)
request.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 30 * time.Second}
response, err := client.Do(request)
if err != nil {
panic(err)
}
defer response.Body.Close()
responseBody, err := io.ReadAll(response.Body)
if err != nil {
panic(err)
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody))
}
fmt.Print(string(responseBody))
}
{
"object": "list",
"data": [
{
"id": "ur_6a8c0e2g4j6m8p0r2t4w6y8b0d",
"object": "usage_record",
"livemode": true,
"subject": "ses_q8v1m3n7p4r6s9t0wxyhk5zba2",
"units": "seconds",
"quantity": 412,
"occurred_at": "2026-10-17T18:07:00Z",
"status": "accepted",
"rejection": null,
"license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
"statement": "stmt_3d5f7h9k1m3p5r7t9w1y3a5c7e",
"created_at": "2026-10-17T19:00:04Z"
},
{
"id": "ur_8c0e2g4j6m8p0r2t4w6y8b0d2f",
"object": "usage_record",
"livemode": true,
"subject": "gen_2q8v1m3n7p4r6s9t0wxyhk5zba",
"units": "seconds",
"quantity": 3.4,
"occurred_at": "2026-10-17T18:06:03Z",
"status": "rejected",
"rejection": {
"code": "duplicate",
"detail": "ur_4y6a8c0e2g4j6m8p0r2t4w6y8b already reports this generation in seconds."
},
"license": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
"statement": null,
"created_at": "2026-10-17T19:00:04Z"
}
],
"has_more": false,
"next_cursor": null
}{
"type": "https://docs.reflections.ai/errors/parameter_invalid",
"title": "A parameter is invalid",
"status": 400,
"code": "parameter_invalid",
"param": "use.territories[1]",
"detail": "\"UK\" is not an ISO 3166-1 alpha-2 code. Use \"GB\".",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/invalid_api_key",
"title": "The API key is not valid",
"status": 401,
"code": "invalid_api_key",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/account_not_connected",
"title": "The licensee has not connected your platform",
"status": 403,
"code": "account_not_connected",
"detail": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba has no active connection with your account.",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/idempotency_key_in_use",
"title": "A request with this key is still running",
"status": 409,
"code": "idempotency_key_in_use",
"detail": "Retry with the same key after a short wait.",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/idempotency_key_reused",
"title": "This key was used for a different request",
"status": 422,
"code": "idempotency_key_reused",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "https://docs.reflections.ai/errors/rate_limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "invalid_request",
"request_id": "<string>",
"detail": "<string>",
"param": "<string>",
"doc_url": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "invalid_request",
"request_id": "<string>",
"detail": "<string>",
"param": "<string>",
"doc_url": "<string>"
}Authorizations
Your secret key, rk_test_… or rk_live_…, sent as Authorization: Bearer <key>. Keep it
on your server. Restricted keys carry only the scopes you give them.
Headers
The dated API version. Defaults to the version your account is pinned to.
Example:
"2026-10-15"
Act for a connected licensee. The value is the licensee's account ID. Requires an active connection between that account and yours.
Pattern:
^acct_[0-9a-hjkmnp-tv-z]{26}$A unique key for this operation, up to 255 characters. In test mode, POST keys are scoped to your account and mode and bind the endpoint and body for 24 hours. A different endpoint or body with the same key is refused.
Initial live check and generation creation require a nonempty key. Each operation has a
separate account-scoped namespace; retain the same API key, body and idempotency key for
retries within 24 hours of creation. A pending check returns 202 with status: "checking".
Completed checks replay their sealed response; successful generation POSTs replay the
original accepted 202, so use GET for current state. Live verification is a read-only
query that returns a fresh verification ID on each call, without exact response caching.
The broader delegated-account contract also scopes keys to Reflections-Account;
delegated requests and the other planned live POST operations remain unsupported.
Maximum string length:
255Body
application/json
1 to 1,000 records. Each is accepted or rejected on its own.
Required array length:
1 - 1000 elementsShow child attributes
Show child attributes
Response
The created records, accepted or rejected one by one.
Always list.
Allowed value:
"list"Whether another page exists.
Pass as cursor to read the next page.
Usage records. Report usage returns them in the order you sent; List usage records returns them newest first.
Show child attributes
Show child attributes