> For the complete documentation index, see [llms.txt](https://docs.archera.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archera.ai/api-reference/beta-api/allocation-reports-beta.md).

# 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"}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archera.ai/api-reference/beta-api/allocation-reports-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.