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

# Get costs

> Get cost, bucketed by period and optionally grouped by one dimension (customer/feature/model/provider).

<CodeGroup>
  ```python Python theme={null}
  import weflayr

  client = weflayr.client(api_key="wf-...")
  ```

  ```js Node.js theme={null}
  const weflayr = require('weflayr');

  const client = weflayr.client({ apiKey: 'wf-...' });
  ```

  ```bash cURL theme={null}
  # Passed as a Bearer token on every request
  export WEFLAYR_API_KEY="wf-..."
  ```
</CodeGroup>

## Get costs

<CodeGroup>
  ```python Python theme={null}
  from weflayr.openapi.models import CostsInput

  client.get_costs(body=CostsInput.from_dict({
      "date_from": "2026-06-01",
      "aggregate": "week",
      "group_by": "customer",
      "customer_tags": {"region": ["EU", "NA"], "plan": "premium"},
      "run_tags": {"agent": ["orchestrator", "qa"]},
  }))
  ```

  ```js Node.js theme={null}
  await weflayr.api.getCosts({
    client,
    throwOnError: true,
    body: {
      dateFrom: '2026-06-01',
      aggregate: 'week',
      groupBy: 'customer',
      customerTags: { region: ['EU', 'NA'], plan: 'premium' },
      runTags: { agent: ['orchestrator', 'qa'] },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://app.weflayr.com/api/costs/ \
    -H "Authorization: Bearer $WEFLAYR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "date_from": "2026-06-01",
      "aggregate": "week",
      "group_by": "customer",
      "customer_tags": {"region": ["EU", "NA"], "plan": "premium"},
      "run_tags": {"agent": ["orchestrator", "qa"]}
    }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "rows": [
    {"date_from": "2026-06-01", "date_to": "2026-06-07", "customer": "c_123", "cost": 342.87, "avg_feature_run_cost": 1.42, "max_feature_run_cost": 6.10},
    {"date_from": "2026-06-01", "date_to": "2026-06-07", "customer": "c_456", "cost": 128.05, "avg_feature_run_cost": 0.85, "max_feature_run_cost": 2.30},
    {"date_from": "2026-06-08", "date_to": "2026-06-14", "customer": "c_123", "cost": 401.20, "avg_feature_run_cost": 1.55, "max_feature_run_cost": 7.40}
  ],
  "next_cursor": null,
  "has_more": false
}
```

Only the field named by `group_by` is present on each row (`customer` above); it's omitted entirely when `group_by` is unset.

**Input params:** passed in the request body.

<ParamField body="date_from" type="&#x22;YYYY-MM-DD&#x22;" required>
  Start of the period, inclusive.
</ParamField>

<ParamField body="date_to" type="&#x22;YYYY-MM-DD&#x22;">
  End of the period, inclusive. Defaults to today.
</ParamField>

<ParamField body="aggregate" type="&#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;quarter&#x22; | &#x22;year&#x22; | &#x22;all&#x22;" default="&#x22;day&#x22;">
  One row per period; `"all"` collapses the whole date range into a single row (per `group_by`, if set).
</ParamField>

<ParamField body="group_by" type="&#x22;customer&#x22; | &#x22;feature&#x22; | &#x22;model&#x22; | &#x22;provider&#x22;">
  Split each period into one row per dimension value. Omit for one row per period.
</ParamField>

<ParamField body="customers" type="list[string]">
  Restrict to these customers. Omit for every customer. See [Get customers](/api/metadata#get-customers).
</ParamField>

<ParamField body="features" type="list[string]">
  Restrict to these feature tags. Omit for every feature. See [Get features](/api/metadata#get-features).
</ParamField>

<ParamField body="models" type="list[string]">
  Restrict to these models. Omit for every model. See [Get models](/api/metadata#get-models).
</ParamField>

<ParamField body="providers" type="list[string]">
  Restrict to these providers. Omit for every provider. See [Get providers](/api/metadata#get-providers).
</ParamField>

<ParamField body="customer_tags" type="{tag_key: list[string] | string}">
  Restrict to customers carrying these tags (AND across `tag_key`, OR within a `tag_key`'s values).
</ParamField>

<ParamField body="run_tags" type="{tag_key: list[string] | string}">
  Restrict to runs carrying these tags (AND across `tag_key`, OR within a `tag_key`'s values).
</ParamField>

<ParamField body="apply_credits" type="boolean" default="false">
  Apply [free AI credits](/configure/free-ai-credits) discounts to `cost`. Never applied to `avg_feature_run_cost`/`max_feature_run_cost`, which always report gross cost.
</ParamField>

<ParamField body="limit" type="integer" default="100">
  Max number of rows to fetch. Max `1000`.
</ParamField>

<ParamField body="cursor" type="string">
  The route is paginated: pass the previous page's `next_cursor` to fetch the next page. PS: `has_more` from the output says whether another page exists.
</ParamField>