cURL

: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"

curl --fail-with-body --max-time 30 'https://app.reflections.ai/v1/escalations?limit=10' \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15"

import { env, exit } from "node:process";

const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");

const response = await fetch("https://app.reflections.ai/v1/escalations?limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Reflections-Version": "2026-10-15",
  },
  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 os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
    raise ValueError("Set REFLECTIONS_KEY before running this example")

headers = {
    "Authorization": f"Bearer {apiKey}",
    "Reflections-Version": "2026-10-15",
}
request = Request("https://app.reflections.ai/v1/escalations?limit=10",
                  method="GET", headers=headers)
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"
    "time"
)

func main() {
    apiKey := os.Getenv("REFLECTIONS_KEY")
    if apiKey == "" {
        panic("Set REFLECTIONS_KEY before running this example")
    }

    request, err := http.NewRequest("GET", "https://app.reflections.ai/v1/escalations?limit=10", nil)
    if err != nil {
        panic(err)
    }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Reflections-Version", "2026-10-15")
    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": "esc_hk5zba2q8v1m3n7p4r6s9t0wxy",
      "object": "escalation",
      "livemode": true,
      "reason": "release_review",
      "reviewer": "talent",
      "status": "open",
      "expires_at": "2026-10-24T18:00:12Z",
      "resolved_at": null,
      "note": null,
      "subject": {
        "object": "generation",
        "id": "gen_6s9t0wxyhk5zba2q8v1m3n7p4r"
      },
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "license_revision": "lrv_p4r6s9t0wxyhk5zba2q8v1m3n7",
      "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "licensee_name": "Ridgeline",
      "platform": "acct_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "platform_name": "Northlight",
      "use": {
        "modality": "image",
        "kind": "depiction",
        "purpose": "advertising",
        "commercial": true,
        "channels": [
          "social",
          "web"
        ],
        "territories": [
          "US",
          "CA"
        ]
      },
      "inputs": [
        {
          "role": "prompt",
          "text": "Maya Okafor holding our new trail shoe on a rocky ridge at sunrise"
        },
        {
          "role": "reference",
          "sha256": "5e0b7c2d9f4a1e6b3c8d0f2a4e6b8c0d2f4a6e8b0c2d4f6a8e0b2c4d6f8a0b2c",
          "media_type": "image/jpeg",
          "url": "https://files.reflections.ai/esc_hk5zba2q8v1m3n7p4r6s9t0wxy/inputs/1?expires=1792262700&signature=i4wRIMXgvdxqeGBa4WCRRBqTCFlu1VQFXABNACbjwUY"
        }
      ],
      "reasons": [],
      "findings": [
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.requiredAttributes",
          "attribute": "identity.samePerson",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.adjustments",
          "attribute": "appearance.wardrobe",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.neverExtras",
          "rule": "Do not show alcohol or tobacco.",
          "result": "preserved"
        }
      ],
      "artifact": {
        "sha256": "9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a",
        "media_type": "image/png",
        "url": "https://files.reflections.ai/esc_hk5zba2q8v1m3n7p4r6s9t0wxy/artifact?expires=1792262700&signature=l63aNVqWPu8FjVP3LV1CGjGXEWmx83-lpwiTA5r4V8I"
      },
      "request_digest": "sha256:bf94817766d56d92211d12f5ff51a3dc1a6d5cb4be2877417b08251fe38c386a",
      "review_url": "https://app.reflections.ai/review/esc_hk5zba2q8v1m3n7p4r6s9t0wxy",
      "decision": null,
      "decided_by": null,
      "created_at": "2026-10-17T18:00:12Z"
    },
    {
      "id": "esc_czjcwnr6p65hakf55easq1aqa6",
      "object": "escalation",
      "livemode": true,
      "reason": "release_review",
      "reviewer": "talent",
      "status": "open",
      "expires_at": "2026-10-24T18:08:53Z",
      "resolved_at": null,
      "note": null,
      "subject": {
        "object": "generation",
        "id": "gen_estxjc1sw4d0fbyra0jfd7x184"
      },
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "license_revision": "lrv_p4r6s9t0wxyhk5zba2q8v1m3n7",
      "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "licensee_name": "Ridgeline",
      "platform": "acct_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "platform_name": "Northlight",
      "use": {
        "modality": "image",
        "kind": "depiction",
        "purpose": "advertising",
        "commercial": true,
        "channels": [
          "social",
          "web"
        ],
        "territories": [
          "US",
          "CA"
        ]
      },
      "inputs": [
        {
          "role": "prompt",
          "text": "Maya Okafor holding our new trail shoe on a rocky ridge at sunrise"
        },
        {
          "role": "reference",
          "sha256": "5e0b7c2d9f4a1e6b3c8d0f2a4e6b8c0d2f4a6e8b0c2d4f6a8e0b2c4d6f8a0b2c",
          "media_type": "image/jpeg",
          "url": "https://files.reflections.ai/esc_czjcwnr6p65hakf55easq1aqa6/inputs/1?expires=1792262700&signature=IlWsHoYkr9dxXtR-oVKqtnjny--ufP0G0Lm4Mfbmm7o"
        }
      ],
      "reasons": [],
      "findings": [
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.requiredAttributes",
          "attribute": "identity.samePerson",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.adjustments",
          "attribute": "appearance.wardrobe",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.neverExtras",
          "rule": "Do not show alcohol or tobacco.",
          "result": "preserved"
        }
      ],
      "artifact": {
        "sha256": "85ccdc0c8087515ce6685fb5a44f0ac2f6e628919fa9b9b0256611712e973342",
        "media_type": "image/png",
        "url": "https://files.reflections.ai/esc_czjcwnr6p65hakf55easq1aqa6/artifact?expires=1792262700&signature=iyg2YgE8I5U-hyhnpLZ1BMVeZt9gweB2kIPFRNRNoIE"
      },
      "request_digest": "sha256:bf94817766d56d92211d12f5ff51a3dc1a6d5cb4be2877417b08251fe38c386a",
      "review_url": "https://app.reflections.ai/review/esc_czjcwnr6p65hakf55easq1aqa6",
      "decision": null,
      "decided_by": null,
      "created_at": "2026-10-17T18:08:53Z"
    }
  ],
  "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/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>"
}

Escalations

List escalations

Planned contract — unavailable in test and live modes. This operation is a protocol reference, not a callable endpoint. Start with the working sandbox quickstart.

The review queue: escalated checks and held outputs that the talent’s side decides, for every talent whose mandate gives you review_outputs. Pass status=open for the items waiting on you, oldest expires_at first. Escalations under platform licenses are reviewed by Reflections and do not appear here.

Restricted keys need escalations:write.

GET

escalations

cURL

: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"

curl --fail-with-body --max-time 30 'https://app.reflections.ai/v1/escalations?limit=10' \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15"

import { env, exit } from "node:process";

const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");

const response = await fetch("https://app.reflections.ai/v1/escalations?limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Reflections-Version": "2026-10-15",
  },
  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 os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
    raise ValueError("Set REFLECTIONS_KEY before running this example")

headers = {
    "Authorization": f"Bearer {apiKey}",
    "Reflections-Version": "2026-10-15",
}
request = Request("https://app.reflections.ai/v1/escalations?limit=10",
                  method="GET", headers=headers)
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"
    "time"
)

func main() {
    apiKey := os.Getenv("REFLECTIONS_KEY")
    if apiKey == "" {
        panic("Set REFLECTIONS_KEY before running this example")
    }

    request, err := http.NewRequest("GET", "https://app.reflections.ai/v1/escalations?limit=10", nil)
    if err != nil {
        panic(err)
    }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Reflections-Version", "2026-10-15")
    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": "esc_hk5zba2q8v1m3n7p4r6s9t0wxy",
      "object": "escalation",
      "livemode": true,
      "reason": "release_review",
      "reviewer": "talent",
      "status": "open",
      "expires_at": "2026-10-24T18:00:12Z",
      "resolved_at": null,
      "note": null,
      "subject": {
        "object": "generation",
        "id": "gen_6s9t0wxyhk5zba2q8v1m3n7p4r"
      },
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "license_revision": "lrv_p4r6s9t0wxyhk5zba2q8v1m3n7",
      "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "licensee_name": "Ridgeline",
      "platform": "acct_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "platform_name": "Northlight",
      "use": {
        "modality": "image",
        "kind": "depiction",
        "purpose": "advertising",
        "commercial": true,
        "channels": [
          "social",
          "web"
        ],
        "territories": [
          "US",
          "CA"
        ]
      },
      "inputs": [
        {
          "role": "prompt",
          "text": "Maya Okafor holding our new trail shoe on a rocky ridge at sunrise"
        },
        {
          "role": "reference",
          "sha256": "5e0b7c2d9f4a1e6b3c8d0f2a4e6b8c0d2f4a6e8b0c2d4f6a8e0b2c4d6f8a0b2c",
          "media_type": "image/jpeg",
          "url": "https://files.reflections.ai/esc_hk5zba2q8v1m3n7p4r6s9t0wxy/inputs/1?expires=1792262700&signature=i4wRIMXgvdxqeGBa4WCRRBqTCFlu1VQFXABNACbjwUY"
        }
      ],
      "reasons": [],
      "findings": [
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.requiredAttributes",
          "attribute": "identity.samePerson",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.adjustments",
          "attribute": "appearance.wardrobe",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.neverExtras",
          "rule": "Do not show alcohol or tobacco.",
          "result": "preserved"
        }
      ],
      "artifact": {
        "sha256": "9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a",
        "media_type": "image/png",
        "url": "https://files.reflections.ai/esc_hk5zba2q8v1m3n7p4r6s9t0wxy/artifact?expires=1792262700&signature=l63aNVqWPu8FjVP3LV1CGjGXEWmx83-lpwiTA5r4V8I"
      },
      "request_digest": "sha256:bf94817766d56d92211d12f5ff51a3dc1a6d5cb4be2877417b08251fe38c386a",
      "review_url": "https://app.reflections.ai/review/esc_hk5zba2q8v1m3n7p4r6s9t0wxy",
      "decision": null,
      "decided_by": null,
      "created_at": "2026-10-17T18:00:12Z"
    },
    {
      "id": "esc_czjcwnr6p65hakf55easq1aqa6",
      "object": "escalation",
      "livemode": true,
      "reason": "release_review",
      "reviewer": "talent",
      "status": "open",
      "expires_at": "2026-10-24T18:08:53Z",
      "resolved_at": null,
      "note": null,
      "subject": {
        "object": "generation",
        "id": "gen_estxjc1sw4d0fbyra0jfd7x184"
      },
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "license_revision": "lrv_p4r6s9t0wxyhk5zba2q8v1m3n7",
      "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "licensee_name": "Ridgeline",
      "platform": "acct_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "platform_name": "Northlight",
      "use": {
        "modality": "image",
        "kind": "depiction",
        "purpose": "advertising",
        "commercial": true,
        "channels": [
          "social",
          "web"
        ],
        "territories": [
          "US",
          "CA"
        ]
      },
      "inputs": [
        {
          "role": "prompt",
          "text": "Maya Okafor holding our new trail shoe on a rocky ridge at sunrise"
        },
        {
          "role": "reference",
          "sha256": "5e0b7c2d9f4a1e6b3c8d0f2a4e6b8c0d2f4a6e8b0c2d4f6a8e0b2c4d6f8a0b2c",
          "media_type": "image/jpeg",
          "url": "https://files.reflections.ai/esc_czjcwnr6p65hakf55easq1aqa6/inputs/1?expires=1792262700&signature=IlWsHoYkr9dxXtR-oVKqtnjny--ufP0G0Lm4Mfbmm7o"
        }
      ],
      "reasons": [],
      "findings": [
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.requiredAttributes",
          "attribute": "identity.samePerson",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.adjustments",
          "attribute": "appearance.wardrobe",
          "result": "preserved"
        },
        {
          "term": "license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.neverExtras",
          "rule": "Do not show alcohol or tobacco.",
          "result": "preserved"
        }
      ],
      "artifact": {
        "sha256": "85ccdc0c8087515ce6685fb5a44f0ac2f6e628919fa9b9b0256611712e973342",
        "media_type": "image/png",
        "url": "https://files.reflections.ai/esc_czjcwnr6p65hakf55easq1aqa6/artifact?expires=1792262700&signature=iyg2YgE8I5U-hyhnpLZ1BMVeZt9gweB2kIPFRNRNoIE"
      },
      "request_digest": "sha256:bf94817766d56d92211d12f5ff51a3dc1a6d5cb4be2877417b08251fe38c386a",
      "review_url": "https://app.reflections.ai/review/esc_czjcwnr6p65hakf55easq1aqa6",
      "decision": null,
      "decided_by": null,
      "created_at": "2026-10-17T18:08:53Z"
    }
  ],
  "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/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

Authorization

string

header

required

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

Reflections-Version

string

The dated API version. Defaults to the version your account is pinned to.

Example:

"2026-10-15"

Query Parameters

talent

string

Only escalations for this talent.

Pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$

status

enum<string>

Only escalations with this status. open lists the items waiting on you, oldest expires_at first.

Available options:

open,

allowed,

denied,

expired,

cancelled

reason

enum<string>

Only escalations raised for this reason. release_review lists held outputs.

Available options:

judgment,

unverifiable,

evaluation_unavailable,

release_review

license

string

Only escalations under this license.

Pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$

limit

integer

default:20

Number of objects to return, 1 to 100.

Required range: 1 <= x <= 100

cursor

string

The next_cursor from the previous page.

Response

A page of escalations.

object

string

required

Always list.

Allowed value: "list"

has_more

boolean

required

Whether another page exists.

next_cursor

string | null

Pass as cursor to read the next page.

data

Escalation · object[]

The escalations on this page.

Show child attributes

Overview

Account

Talent

Facets

Resolutions

Licenses

License requests

Connections

Files

Checks

Generations

Sessions

Receipts

Verifications

Revocations

Usage records

Statements

Mandates

Escalations

License drafts

Webhook endpoints

Events

Discovery

OAuth

Test helpers

Webhooks

Real-time

Formats

MCP

List escalations

Authorizations

Headers

Query Parameters

Response