# Usage

## Endpoints

- `GET /platform/usage/records`: [List usage records](https://docs.polymorfa.com/api/usage/list-usage-records)
- `GET /platform/gates`: [List usage gates](https://docs.polymorfa.com/api/usage/list-usage-gates)
- `GET /platform/usage`: [Get usage summary](https://docs.polymorfa.com/api/usage/get-usage-summary)

## List usage records

`GET https://api.polymorfa.com/platform/usage/records` (Platform API)

Required permission: `sessions:read`

Lists usage records, newest first. Filter by project, number (`session`), call (`callId`), meter or calendar month; without `period`, records from every month are listed. A call has one `call.duration` record, and an outgoing Cloud API call also a `call.cloud_pulses` record. Pass `nextCursor` as `cursor` to read the next page with the same filters.

Requires `sessions:read`. Project tokens only access resources in their own project.

### Query parameters

- `projectId` (string). Filter records to this project. Omit to list records from every project you can access.
- `session` (string, length 1–128). Identifier of the connected Polymorfa session.
- `callId` (string, length 1–128, pattern ^[\x21-\x7e]+$). Identifier of the WhatsApp call.
- `meter` (string). Specifies meter for this query parameter. Values: `call.duration`, `call.cloud_pulses`, `campaign.call`, `tts.characters`, `tts.seconds`, `stt.seconds`, `agent.seconds`, `agent.tokens`, `agent.provider_cost`, `channels.peak`, `storage.byte_days`.
- `period` (string, pattern ^\d{4}-(0[1-9]|1[0-2])$). Specifies period for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.
- `cursor` (string, length 1–256). Specifies cursor for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/platform/usage/records" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `records` (array of object, required, max items 100). Records associated with this management usage record page.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `meter` (string, required). Specifies meter for this management usage record. Values: `call.duration`, `call.cloud_pulses`, `campaign.call`, `tts.characters`, `tts.seconds`, `stt.seconds`, `agent.seconds`, `agent.tokens`, `agent.provider_cost`, `channels.peak`, `storage.byte_days`.
    - `quantity` (number, required, min 0). Number of units included for this item.
    - `unit` (string, required). Specifies unit for this management usage record. Values: `second`, `pulse`, `call`, `character`, `token`, `provider_unit`, `channel`, `byte_day`.
    - `dimensions` (object, required). Closed, per-meter attributes. Call meters carry `direction`, `upstream` (`linked_device` or `cloud_api`), `origin`, `participants`, `connections`, `sipLegs` and `video`.
    - `keySource` (string, required). Specifies key source for this management usage record. Values: `none`, `managed`, `customer`.
    - `sourceKind` (string, required). Category assigned to source. Values: `call`, `attempt`, `flow_run`, `conversation`, `asset`, `team`.
    - `sourceId` (string, required). The call id for call meters.
    - `projectId` (string (uuid), required, nullable, format uuid). Original owning project, preserved across usage revisions and number deletion. Null when unknown; project-filtered reads exclude unattributed records.
    - `session` (string, required, nullable). The number (session name) the usage belongs to.
    - `occurredAt` (string (date-time), required, format date-time). When the usage happened. For calls, when the call ended.
    - `recordedAt` (string (date-time), required, format date-time). Timestamp for recorded at.
    - `revision` (integer, required, min 1). Increases when a later observation corrects the record, for example a call end reported after a lost connection.
    - `pricingState` (string, required). `unpriced` while usage is measured but not charged. Values: `unpriced`, `priced`, `waived`, `settled`.
    - `rateCard` (object, required, nullable). The rate card that applied when the usage was recorded. Null while no rate card exists.
      - `id` (string (uuid), required, format uuid). Identifier for this resource.
      - `version` (integer, required). Specifies version for this rate card.
    - `pricedCredits` (number, required, nullable). Credits charged for the record. Null until the record is priced.
  - `nextCursor` (string, required, nullable). Pass as `cursor` for the next page; null on the last page.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "records": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "meter": "call.duration",
        "quantity": 0,
        "unit": "second",
        "dimensions": {},
        "keySource": "none",
        "sourceKind": "call",
        "sourceId": "string",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "session": "string",
        "occurredAt": "2026-09-22T12:00:00Z",
        "recordedAt": "2026-09-22T12:00:00Z",
        "revision": 1,
        "pricingState": "unpriced",
        "rateCard": {
          "id": "00000000-0000-4000-8000-000000000000",
          "version": 0
        },
        "pricedCredits": 0
      }
    ],
    "nextCursor": "string"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## List usage gates

`GET https://api.polymorfa.com/platform/gates` (Platform API)

Required permission: `sessions:read`

Returns every usage gate with its mode, limit, current usage and decisions in the last 30 days. Gate state covers the whole team, so it needs a team API key; project tokens are refused. Pass `session` to include limits that apply per number, and `projectId` to require that the number belongs to that project. The active outbound monthly gate is record-only: an action over its limit is counted but allowed. It cannot be switched to enforce until placement reservations are available. An action whose limit cannot be checked fails with `503`.

Team keys require `sessions:read`. Project tokens are not accepted.

### Query parameters

- `projectId` (string). Use with `session` to require that the number belongs to this project. Gate limits and usage remain team-wide or per number.
- `session` (string, length 1–128). Identifier of the connected Polymorfa session.

### Request

```bash
curl "https://api.polymorfa.com/platform/gates" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `session` (string, required, nullable). Identifier of the connected Polymorfa session.
  - `gates` (array of object, required). Gates associated with this management usage gate list.
    - `key` (string, required). Specifies key for this management usage gate. Values: `calls.outbound_monthly`, `voice.campaigns`, `voice.campaigns.recipients`, `voice.campaigns.calls_monthly`, `voice.channels.concurrent`, `voice.audio_library`, `voice.audio_library.assets`, `voice.flows`, `voice.agents.elevenlabs`, `voice.agents.openai_realtime`, `voice.providers.managed`, `voice.providers.customer_key`, `voice.agent_minutes_monthly`, `voice.tts_characters_monthly`, `voice.stt_minutes_monthly`, `voice.storage.recordings`, `voice.storage.transcripts`.
    - `kind` (string, required). Kind discriminator for this object. Values: `capability`, `quota`, `limit`, `concurrency`.
    - `subject` (string, required). What the limit applies to. Values: `team`, `number`, `project`, `campaign`.
    - `mode` (string, required). `record` counts actions over the limit without refusing them. `enforce` refuses them with `gate_limit_reached`. `off` does not check. Values: `off`, `record`, `enforce`.
    - `active` (boolean, required). Whether an action checks this gate today. Voice automation gates are inactive until those features ship.
    - `limit` (number, required, nullable). For capability gates, 1 when included and 0 when not. Otherwise the limit, or -1 for no limit. Null when the limit applies per number and no `session` was given.
    - `used` (number, required, nullable). Usage this calendar month (UTC) counted against a quota. Per-number quotas count only the current number; retained usage from a deleted number with the same name is excluded.
    - `unit` (string, required, nullable). Specifies unit for this management usage gate. Values: `second`, `pulse`, `call`, `character`, `token`, `provider_unit`, `channel`, `byte_day`, `count`, `minute`.
    - `overLimit` (boolean, required, nullable). Whether the next action would exceed the limit.
    - `decisions` (object, required). Checks over the limit in the last 30 days (UTC).
      - `wouldBlock` (integer, required, min 0). Allowed because the gate records only.
      - `blocked` (integer, required, min 0). Refused because the gate enforces.
      - `evaluationError` (integer, required, min 0). Could not be evaluated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "session": "string",
    "gates": [
      {
        "key": "calls.outbound_monthly",
        "kind": "capability",
        "subject": "team",
        "mode": "off",
        "active": true,
        "limit": 0,
        "used": 0,
        "unit": "second",
        "overLimit": true,
        "decisions": {
          "wouldBlock": 0,
          "blocked": 0,
          "evaluationError": 0
        }
      }
    ]
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get usage summary

`GET https://api.polymorfa.com/platform/usage` (Platform API)

Required permission: `sessions:read`

Returns metered usage for one calendar month (UTC), by meter and by number. Omit `period` for the current month. Usage is measured, not charged: `billingEnabled` is false and no credits are deducted for it. A project token reads its own project; `session` narrows to one number.

Requires `sessions:read`. Project tokens only access resources in their own project.

### Query parameters

- `projectId` (string). Project to read. Omit to total every project in the team.
- `session` (string, length 1–128). Identifier of the connected Polymorfa session.
- `period` (string, pattern ^\d{4}-(0[1-9]|1[0-2])$). Specifies period for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/platform/usage" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `period` (string, required, pattern ^\d{4}-\d{2}$). Calendar month in UTC.
  - `start` (string (date-time), required, format date-time). Specifies start for this management usage summary.
  - `end` (string (date-time), required, format date-time). Specifies end for this management usage summary.
  - `projectId` (string (uuid), required, nullable, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `session` (string, required, nullable). Identifier of the connected Polymorfa session.
  - `billingEnabled` (boolean, required). Always false while usage is measured but not charged.
  - `meters` (array of object, required). Meters associated with this management usage summary.
    - `meter` (string, required). Specifies meter for this management usage meter total. Values: `call.duration`, `call.cloud_pulses`, `campaign.call`, `tts.characters`, `tts.seconds`, `stt.seconds`, `agent.seconds`, `agent.tokens`, `agent.provider_cost`, `channels.peak`, `storage.byte_days`.
    - `unit` (string, required). Specifies unit for this management usage meter total. Values: `second`, `pulse`, `call`, `character`, `token`, `provider_unit`, `channel`, `byte_day`.
    - `keySource` (string, required). Specifies key source for this management usage meter total. Values: `none`, `managed`, `customer`.
    - `quantity` (number, required, min 0). Number of units included for this item.
    - `records` (integer, required, min 0). Specifies records for this management usage meter total.
  - `numbers` (array of object, required, max items 100). Totals per number, most call time first.
    - `session` (string, required). Identifier of the connected Polymorfa session.
    - `projectId` (string (uuid), required, nullable, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `meters` (array of object, required). Meters associated with this number.
      - `meter` (string, required). Specifies meter for this management usage meter total. Values: `call.duration`, `call.cloud_pulses`, `campaign.call`, `tts.characters`, `tts.seconds`, `stt.seconds`, `agent.seconds`, `agent.tokens`, `agent.provider_cost`, `channels.peak`, `storage.byte_days`.
      - `unit` (string, required). Specifies unit for this management usage meter total. Values: `second`, `pulse`, `call`, `character`, `token`, `provider_unit`, `channel`, `byte_day`.
      - `keySource` (string, required). Specifies key source for this management usage meter total. Values: `none`, `managed`, `customer`.
      - `quantity` (number, required, min 0). Number of units included for this item.
      - `records` (integer, required, min 0). Specifies records for this management usage meter total.
  - `numbersTruncated` (boolean, required). True when more than 100 numbers had usage.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "period": "string",
    "start": "2026-09-22T12:00:00Z",
    "end": "2026-09-22T12:00:00Z",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "session": "string",
    "billingEnabled": true,
    "meters": [
      {
        "meter": "call.duration",
        "unit": "second",
        "keySource": "none",
        "quantity": 0,
        "records": 0
      }
    ],
    "numbers": [
      {
        "session": "string",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "meters": [
          {
            "meter": "call.duration",
            "unit": "second",
            "keySource": "none",
            "quantity": 0,
            "records": 0
          }
        ]
      }
    ],
    "numbersTruncated": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```
