> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports API

> Create, schedule, preview, and run Costory cost reports over HTTP. The same API powers scheduling from the UI and from chat via the Costory MCP.

The Reports API creates and schedules the cost reports described in [Cost Reports](/features/slack-reports). Every report you build in the UI or ask the [Costory MCP](/features/mcp) to create resolves to a call against these endpoints, so anything you can schedule by hand you can automate here.

Authenticate with a bearer token as described in the [API overview](/api-reference/overview).

## A report in one call

A report ties together a scope, one or more widgets, a cadence, and the channels it goes to. [Create a report](/api-reference/reports/create-a-report) accepts all of it in a single `POST /reports` body:

* `context` sets the shared scope, group-by, and period the widgets inherit.
* `widgets` holds the trend graph, the top and bottom ranking, or the Digest breakdown to render.
* `scheduledPeriod` and `scheduledWeekday` set the cadence (or `null` for an on-demand report you trigger yourself).
* `destinations` lists the Slack, Microsoft Teams, or email targets the report fans out to on every run.

Before scheduling, [preview a widget](/api-reference/reports/preview-a-report-widget) or [send a test delivery](/api-reference/reports/send-a-test-report) to check the format and data.

## Endpoints

Use the pages in this section to see the full schema and try each call against staging.