---
title: "Get app metered usage"
method: GET
path: "/api/v1/apps/{app_id}/usage"
tags: ["Apps"]
---

# Get app metered usage

`GET /api/v1/apps/{app_id}/usage`

Returns billing usage records from ClickHouse. Defaults to 7-day window if dates not specified.

## Path parameters

- `app_id` string, required — Hex app identifier

## Query parameters

- `start_date` string, date-time, nullable — Start date (ISO 8601)
- `end_date` string, date-time, nullable — End date (ISO 8601)
- `limit` integer — Max records to return
- `offset` integer — Records to skip

## Response `200`

Usage records with cost breakdown

- AppUsageResponse — App usage response with cost summary.
  - `usage` MeteredUsageResponse[], required — Usage records
    - `instance_id` string, required — CVM instance UUID
    - `project_id` integer, required — Project database ID
    - `team_id` integer, required — Team database ID
    - `timestamp` string, required — Record timestamp (ISO 8601)
    - `event_type` string, required — Usage event type
    - `cost` number, required — Cost in USD
    - `details` string, nullable, required — JSON usage details
    - `usage_type` string, required — Billing category: compute, storage, etc.
    - `billing_start` string, required — Billing period start (date)
    - `billing_end` string, required — Billing period end (date)
    - `duration_minutes` number, required — Usage duration in minutes
    - `billing_key` string, required — Unique billing record key
    - `billing_hour` string, required — Billing hour bucket
    - `billing_day` string, required — Billing day bucket
  - `total` integer, required — Number of records returned
  - `total_cost` number, required — Sum of costs in USD

## Other responses

- `400` — end_date before start_date
- `401` — Not authenticated
- `403` — No workspace access
- `404` — App not found
- `422` — Validation Error

---

[API](https://skmtc.net/phala/apis/phala-cloud-api.md) · [All operations](https://skmtc.net/phala/apis/phala-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phala/phala-cloud-api/versions/83c6ae62e860/schema)