---
title: "List read-only current provider usage summaries"
method: GET
path: "/providers/current/usage-summary"
tags: ["Usage summary"]
---

# List read-only current provider usage summaries

`GET /providers/current/usage-summary`

## Request

- Base URL: `https://platform-api.homejourney.sg/v1`
- URL: `https://platform-api.homejourney.sg/v1/providers/current/usage-summary`
- Auth: HTTP bearer

Returns customer-visible usage summaries for all platform launch verticals when the authenticated automation client has `platform.billing_owner_visibility.read`. External URL: `/v1/providers/current/usage-summary`. Current Next.js implementation path: `/api/platform/v1/providers/current/usage-summary`. This read-only route does not require `Idempotency-Key`; it exposes plan state, usage-summary test IDs, approved rollup posture, and observe-only billing side-effect blocking only. It never reads usage event tables or partner-facing billing tables, returns raw usage payloads or raw payment payloads, sends invoices, collects payments, enforces quota, suspends credentials, or calls external finance providers.

## Headers

- `X-Correlation-Id` string

## Response `200`

Read-only customer-visible usage summaries.

- UsageSummaryResponse
  - `summaries` UsageSummaryItem[], required
    - `module_id` 'agent' | 'agency' | 'business' | 'mortgage' | 'legal' | 'developer' | 'renovation', required
    - `label` string, required
    - `workspace_root` string, required
    - `plan_state` 'restricted_workspace_observe_only', required
    - `billing_owner` string, required
    - `invoice_contact` string, email, required
    - `billing_period` string, required
    - `usage_unit` 'api_call' | 'tool_call' | 'cli_call' | 'webhook_delivery' | 'webhook_replay' | 'site_view' | 'lead_submission' | 'schedule_request' | 'crm_delivery' | 'storage_gb_month' | 'signed_url' | 'document_scan' | 'source_refresh' | 'source_snapshot' | 'sandbox_reset' | 'certification_review' | 'marketplace_install', required
    - `included_units` integer, required
    - `used_units` integer, required
    - `billable_units` integer, required
    - `quota_state` 'observe' | 'warning' | 'soft_block' | 'hard_block' | 'suspended', required
    - `invoice_state` 'draft' | 'review_required' | 'approved' | 'issued' | 'paid' | 'partially_paid' | 'voided' | 'credited' | 'disputed' | 'uncollectible', required
    - `overage_review_state` 'manual_review_required', required
    - `automatic_overage_enforcement_allowed` false, required
    - `invoice_external_send_allowed` false, required
    - `payment_collection_allowed` false, required
    - `usage_summary_test_id` string, required
    - `usage_event_id` string, required
    - `usage_event_status` 'succeeded' | 'failed' | 'excluded', required
    - `usage_event_surface` 'rest_api' | 'mcp' | 'cli' | 'webhook' | 'hosted_site' | 'widget' | 'official_source' | 'document_handoff' | 'admin_action', required
    - `usage_event_route_or_tool` string, required
    - `usage_event_quantity` number, required
    - `source_event_count` integer, required
    - `reconciliation_status` 'pending' | 'matched' | 'mismatch' | 'adjusted' | 'approved' | 'locked', required
    - `billing_exclusion_reason` 'free_allowance' | 'sandbox' | 'test_fixture' | 'duplicate' | 'failed_before_chargeable_work' | 'manual_adjustment' | 'internal_first_party' | 'enterprise_exception' | 'null', nullable, required
    - `observe_only_mode` 'observe_only', required
    - `allowed_actions` string[], required
    - `blocked_actions` string[], required
    - `raw_usage_event_payload_visible` false, required
    - `raw_payment_payload_visible` false, required
    - `quota_enforcement_allowed` false, required
    - `credential_suspension_allowed` false, required
    - `proof_command` string, required
    - `evidence_path` string, required
    - `launch_ready` boolean, required
    - `blocker` string, nullable, required
    - `next_action` string, required
  - `summary` UsageSummaryAggregate, required
    - `total_verticals` integer, required
    - `plan_state_visible` integer, required
    - `billing_owner_visible` integer, required
    - `invoice_contact_visible` integer, required
    - `billing_owner_visibility_gates` integer, required
    - `partner_billing_table_reads_deferred` integer, required
    - `usage_events_present` integer, required
    - `customer_visible_usage_summaries` integer, required
    - `automatic_overage_enforcement_blocked` integer, required
    - `billing_owner_gate_side_effects_blocked` integer, required
    - `launch_ready_contracts` integer, required
    - `source_contract` 'vertical_billing_usage_contract', required
    - `usage_read_model` 'customer_visible_contract_no_usage_event_table_reads', required
    - `billing_write_model` 'observe_only_no_invoice_or_payment_side_effects', required
  - `authorization` UsageSummaryAuthorization, required
    - `organization_id` string, uuid, required
    - `client_id` string, uuid, required
    - `api_key_id` string, uuid, required
    - `required_scope` 'platform.billing_owner_visibility.read', required
    - `granted_billing_scopes` PlatformScope[], required
    - `actor_model` 'api_key_automation_client', required
    - `data_access` 'customer_visible_usage_summary_contract_only', required
    - `table_access` 'no_usage_event_or_partner_billing_table_reads', required
    - `mutation_access` 'usage_billing_writes_deferred', required
  - `public_safety` UsageSummaryPublicSafety, required
    - `usage_event_table_reads_allowed` false, required
    - `partner_billing_table_reads_allowed` false, required
    - `raw_usage_event_payload_visible` false, required
    - `raw_payment_payload_visible` false, required
    - `invoice_external_send_allowed` false, required
    - `payment_collection_allowed` false, required
    - `quota_enforcement_allowed` false, required
    - `credential_suspension_allowed` false, required
    - `external_finance_calls` false, required
    - `billing_write_mutations_enabled` false, required
  - `principal` Principal, required (unresolved $ref)
  - `livemode` boolean, required
  - `request_id` string, required

## Other responses

- `400`: Request validation failed.
- `401`: Missing or invalid platform API key.
- `403`: Credential, environment, or scope is not allowed.
- `404`: Platform API feature or resource is not available.
- `429`: Rate limit exceeded.
- `500`: Unexpected platform API failure.

---

[API](https://skmtc.dev/homejourney/apis/homejourney-platform-api.md) · [All operations](https://skmtc.dev/homejourney/apis/homejourney-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/homejourney/apis/homejourney-platform-api/revisions/a2c6fe063db1?raw)