# 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

Turn on the project metrics endpoint with a `PATCH`. When enabled, the read response returns the connection details (`url`, `username`, `password`) for scraping metrics.

```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 } }'
```

## 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.