Skip to content
SupaCloud Docs
Select themeSelect language

`GET /api/reports/inbox` — the #1178 P3 per-inbox counter: what a public support inbox received, refused, handed off, answered from the documentation and cost over a rolling 24 hours, plus the derivative surge alarm.

GET
/api/reports/inbox
curl --request GET \
  --url https://example.com/api/reports/inbox \
  --cookie supacloud_session=<supacloud_session>

WORKSPACE-ADMIN, unlike the overview beside it. Refusal and hand-off counts are operational data about an inbox under load; a front-end filter that merely hides the tab is not a gate, so the gate is here. It composes with the same intelligence.suggestions entitlement the rest of the hub uses.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

The endpoint’s body. An envelope rather than a bare array so a later facet or total can be added without breaking the shape.

object
items
required
Array<object>

One inbox’s rolling 24-hour picture.

object
channel
required

chatwoot | intercom.

string
conversations_24h
required
integer format: int64
cost_unknown_tasks
required

Runs with no outcome row. ABSENT is not zero — without this number an unknown spend reads as a free one.

integer format: int64
cost_usd_24h
required

REAL spend from task_outcomes, never a second estimate: the ceiling’s token estimator has to decide before a call, this reports after one.

number format: double
docs_answers_24h
required

#1178 P0 — questions answered from the documentation corpus, at no model cost. The one figure that says what the cheap path SAVED.

integer format: int64
handoffs_24h
required

Ceilings that fired on the QUALITY axis (conversation.handed_off).

integer format: int64
inbound_24h
required
integer format: int64
inbound_median_hour
required
number format: double
inbound_this_hour
required
integer format: int64
refusals_24h
required

Ceilings that fired on the COST axis (conversation.rate_limited).

integer format: int64
resource_id
required

The bound channel resource — the inbox itself.

string format: uuid
resource_name
required
string
surge
required

The DERIVATIVE alarm: this hour against this inbox’s own median.

boolean
surge_factor
required

Echoed so the reader can see which multiple was applied, rather than having to trust a bare boolean.

number format: double
surge_floor
required
integer format: int64
tokens_24h
required
integer format: int64
Examplegenerated
{
  "items": [
    {
      "channel": "example",
      "conversations_24h": 1,
      "cost_unknown_tasks": 1,
      "cost_usd_24h": 1,
      "docs_answers_24h": 1,
      "handoffs_24h": 1,
      "inbound_24h": 1,
      "inbound_median_hour": 1,
      "inbound_this_hour": 1,
      "refusals_24h": 1,
      "resource_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "resource_name": "example",
      "surge": true,
      "surge_factor": 1,
      "surge_floor": 1,
      "tokens_24h": 1
    }
  ]
}

401

Section titled “401”

Authentication required

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

403

Section titled “403”

Permission denied

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

500

Section titled “500”

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}