Skip to content
Shortcut: /, ⌘K or Ctrl+K

Usage

View as Markdown

List usage records

GET/platform/usage/recordsPlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring

    Filter records to this project. Omit to list records from every project you can access.

  • sessionstringlength1–128

    Identifier of the connected Polymorfa session.

  • callIdstringlength1–128pattern^[\x21-\x7e]+$

    Identifier of the WhatsApp call.

  • meterstring

    Specifies meter for this query parameter.

    Allowed valuescall.durationcall.cloud_pulsescampaign.calltts.characterstts.secondsstt.secondsagent.secondsagent.tokensagent.provider_costchannels.peakstorage.byte_days
  • periodstringpattern^\d{4}-(0[1-9]|1[0-2])$

    Specifies period for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • cursorstringlength1–256

    Specifies cursor for this query parameter.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/usage/recordscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/usage/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
  }
}

List usage gates

GET/platform/gatesPlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring

    Use with session to require that the number belongs to this project. Gate limits and usage remain team-wide or per number.

  • sessionstringlength1–128

    Identifier of the connected Polymorfa session.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/gatescURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/gates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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
        }
      }
    ]
  }
}

Get usage summary

GET/platform/usagePlatform API
Base URL
https://api.polymorfa.com
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

  • projectIdstring

    Project to read. Omit to total every project in the team.

  • sessionstringlength1–128

    Identifier of the connected Polymorfa session.

  • periodstringpattern^\d{4}-(0[1-9]|1[0-2])$

    Specifies period for this query parameter.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 9 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/usagecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/usage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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
  }
}