# Usage and billing

The Management API offers two reporting views. Project usage gives the current billing-month view for one project. Organization usage reports query a custom date range across selected projects or payment methods. The same surface manages payment methods and project metrics export. MK.IO bills on metered, pay-as-you-go usage, so these reports map directly to what you are charged.

## Current project usage

For a quick month-to-date view of one project:

```bash
curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/usage" \
  -H "Authorization: Bearer <YOUR_TOKEN>"
```

This returns usage since the start of the current month, grouped by meter.

## Date-range usage reports

For any other range, post a query to the reporting endpoint. `startDate` is inclusive and `endDate` is exclusive, both as `YYYY-MM-DD` in UTC.

```bash
curl -X POST "https://app.mk.io/api/v1/organization/reports/usage" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-01-01",
    "endDate": "2026-02-01",
    "granularity": "day",
    "projectNames": ["my-project"]
  }'
```

The query supports:

- `granularity`: `hour`, `day`, `week`, `month`, or `year`. The range is capped by granularity: 31 days for `hour`, one year for `day`, and unbounded for `week` and above.
- `projectNames` or `paymentMethodIds` to filter. These two are mutually exclusive.
- `format`: `json` (default) or `csv`.
- `download`: set `true` to return the report as a file download.
- `filterOnReportedDate`: set `true` to filter by when usage was charged rather than when it occurred, which helps reconcile against invoice dates.

To pull a CSV for finance:

```bash
curl -X POST "https://app.mk.io/api/v1/organization/reports/usage" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-01-01",
    "endDate": "2026-02-01",
    "format": "csv",
    "download": true,
    "filterOnReportedDate": true
  }'
```

## Payment methods

List the organization's payment methods, and read one method's rate card to see per-meter prices:

```bash
curl -X GET "https://app.mk.io/api/v1/organization/paymentMethods" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/organization/paymentMethods/<PAYMENT_METHOD_ID>/rateCard" \
  -H "Authorization: Bearer <YOUR_TOKEN>"
```

Read or replace the method assigned to a project:

```bash
curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/paymentMethod" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X POST "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/paymentMethod" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodId": "<PAYMENT_METHOD_ID>" }'
```

## Enable metrics export

Enabling metrics export is billable. Confirm the action and current rate card before turning it on. Enable the project metrics endpoint with a `PATCH`:

```bash
curl -X PATCH "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/metricsEndpoint" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "enabled": true } }'
```

The read response returns `url`, `username`, and `password`. Treat the username and password as secrets. The URL exposes current Prometheus-format samples through `/federate`; it is not a historical query API.

Source values refresh at approximately 30-second intervals. Faster scraping does not create fresher values. Use external Prometheus-compatible storage and Grafana for retained history, trends, and dashboards. Metrics ending in `_total`, including ETR-290 totals, are cumulative counters. Calculate rates from retained samples.

The export does not provide viewer count, viewer geography, startup time, rebuffering, or player errors. Streaming endpoint request rate and egress bitrate represent delivery traffic, not viewer, session, or concurrency counts.

## What goes wrong

- **A payment method seems stuck on a project.** A method cannot be removed, only replaced with another. Assigning one also activates the project.
- **An hourly report is rejected for too wide a range.** `hour` granularity is limited to 31 days. Use `day` or coarser for longer ranges.
- **Report totals do not match an invoice.** The report defaults to when usage occurred. Set `filterOnReportedDate` to `true` to align with billing dates.

## What comes next

- [Provision org and users](/api-guides/how-to/management/org-provisioning): set up projects before reporting on them.
- [Management API reference](/api-reference/management-api): the full reporting and billing schemas.