# Allocation Reports (Beta)

Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs.

## List available allocation reports

> Catalog of allocation/showback reports a caller can fetch via `GET /allocation-reports/<report_type>`. Each entry declares the query parameters it accepts and the columns its rows will contain.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Allocation Reports (Beta)","description":"Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs."}],"paths":{"/beta/v1/org/{org_id}/allocation-reports":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AllocationReportDescriptor"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Allocation Reports (Beta)"],"summary":"List available allocation reports","description":"Catalog of allocation/showback reports a caller can fetch via `GET /allocation-reports/<report_type>`. Each entry declares the query parameters it accepts and the columns its rows will contain."}}},"components":{"schemas":{"AllocationReportDescriptor":{"type":"object","properties":{"report_type":{"type":"string","description":"Identifier used as the path segment on the get endpoint (`/allocation-reports/<report_type>`)."},"name":{"type":"string","description":"Human-readable report title."},"description":{"type":"string","description":"What the report contains."},"category":{"type":"string","description":"Allocation tier. 'premiums_and_rebates' = Archera-side overlay only. 'commitment' = commitment cost redistributed from holding to usage accounts (typically with overlay alongside). 'cloud_bill' = full cloud bill including commitment + on-demand + Archera adjustments."},"row_grain":{"type":"string","description":"Time grain each row represents: 'monthly' (one row per calendar month, usually paired with another dim) or 'daily' (one row per calendar date)."},"update_cadence":{"type":"string","description":"When the report's underlying data changes. 'daily' = refreshes each day as new utilization lands; current-period previews are available and freeze after the period's invoice closes. 'on_period_close' = single snapshot when the invoice generates; calling for the current period returns empty until close. 'static' = never changes."},"params":{"type":"array","description":"Query parameters this report accepts.","items":{"$ref":"#/components/schemas/AllocationReportParamDescriptor"}},"output_fields":{"type":"array","description":"Columns each row of the report contains.","items":{"$ref":"#/components/schemas/AllocationReportFieldDescriptor"}}},"additionalProperties":false},"AllocationReportParamDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Query parameter name."},"type":{"type":"string","description":"JSON type: 'integer', 'number', 'string', or 'boolean'."},"required":{"type":"boolean","description":"Whether the parameter must be supplied."},"description":{"type":"string","description":"What the parameter controls."}},"additionalProperties":false},"AllocationReportFieldDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Output column name (snake_case in JSON)."},"type":{"type":"string","description":"JSON type of the column value."},"description":{"type":"string","description":"What the column represents."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Fetch one allocation report

> Returns one report's rows for the requested calendar month. Accepted query parameters and returned columns vary by `report_type` — call the list endpoint to discover them. Pass `?format=csv` for a CSV download (default is JSON). Returns 404 for unknown or per-org-hidden reports, and 404 with `code: period_not_available` when the requested (year, month) isn't in this report's available periods — call the /periods endpoint to enumerate what is. marshmallow.ValidationError on bad query params is handled globally as a 400.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Allocation Reports (Beta)","description":"Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs."}],"paths":{"/beta/v1/org/{org_id}/allocation-reports/{report_type":{"get":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Allocation Reports (Beta)"],"summary":"Fetch one allocation report","description":"Returns one report's rows for the requested calendar month. Accepted query parameters and returned columns vary by `report_type` — call the list endpoint to discover them. Pass `?format=csv` for a CSV download (default is JSON). Returns 404 for unknown or per-org-hidden reports, and 404 with `code: period_not_available` when the requested (year, month) isn't in this report's available periods — call the /periods endpoint to enumerate what is. marshmallow.ValidationError on bad query params is handled globally as a 400."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List periods available for an allocation report

> Returns the (year, month) periods this report can be queried for, given the supplied filter params (same shape as the get endpoint minus year/month — those are the dimensions being enumerated). Each entry has `status: "finalized"` for past months backed by an invoice, or `"in_progress"` for the current calendar month when the report's update_cadence is "daily". Sorted most-recent first.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Allocation Reports (Beta)","description":"Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs."}],"paths":{"/beta/v1/org/{org_id}/allocation-reports/{report_type}/periods":{"get":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Allocation Reports (Beta)"],"summary":"List periods available for an allocation report","description":"Returns the (year, month) periods this report can be queried for, given the supplied filter params (same shape as the get endpoint minus year/month — those are the dimensions being enumerated). Each entry has `status: "finalized"` for past months backed by an invoice, or `"in_progress"` for the current calendar month when the report's update_cadence is "daily". Sorted most-recent first."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```