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:

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.

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:

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:

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:

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.

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.