Usage API (alpha)

Some teams want to integrate Tuple call data with tools like DX and Jellyfish. To that end, we offer a usage API. To get access, reach out to support.

Endpoint

GET /api/v2/call_usage

Returns completed calls for the authenticated team, sorted by ended_at ascending.

Authentication

Requests must include a Bearer token in the Authorization header:

Authorization: Bearer sk-tuple-...

Team owners and managers can create and manage API tokens directly from the dashboard. See Managing API tokens below.

Query parameters

Parameter	Required	Description
`since`	Yes	ISO 8601 datetime. Only returns calls that ended at or after this time.
`until`	No	ISO 8601 datetime. Only returns calls that ended before this time. Defaults to now.
`page`	No	Page number for pagination. Defaults to 1.
`per_page`	No	Number of calls per page. Defaults to 100, maximum 1000.

Response

Returns a JSON array of call objects. Default 100 calls per page (max 1000).

[
  {
    "id": 12345,
    "started_at": "2026-03-15T14:30:00.000Z",
    "ended_at": "2026-03-15T15:00:00.000Z",
    "duration_seconds": 1800,
    "call_participations": [
      {
        "id": 67890,
        "joined_at": "2026-03-15T14:30:00.000Z",
        "left_at": "2026-03-15T15:00:00.000Z",
        "user": {
          "email": "alice@example.com"
        }
      }
    ]
  }
]

Pagination headers

Follows RFC 8288 (Web Linking).

Header	Description
`X-Total-Count`	Total number of calls matching the query.
`Link`	Standard `Link` header with `rel="next"` and `rel="prev"` URLs when applicable.

Rate limiting

60 requests per minute per team. Returns 429 Too Many Requests when exceeded.

Error responses

Status	Cause
`401 Unauthorized`	Missing or invalid Bearer token.
`422 Unprocessable Entity`	Malformed `since` or `until` parameter (must be valid ISO 8601).
`429 Too Many Requests`	Rate limit exceeded.

Example

curl -H "Authorization: Bearer sk-tuple-abc123..." \
  "https://production.tuple.app/api/v2/call_usage?since=2026-03-01T00:00:00Z&until=2026-03-31T00:00:00Z"

Managing API tokens

Team owners and managers can create, view, and revoke API tokens from the Tuple dashboard.

Create a token

Open the API tokens page

Go to your team management page.

Create a new token

Click Create token and give it a descriptive name (for example, “DX integration” or “Jellyfish sync”).

Copy the token

Copy the token immediately after creation. The full token is only shown once and cannot be retrieved later.

Revoke a token

To revoke a token, open the menu next to it on the API tokens page and click Revoke. Any integration using that token will immediately lose access.

Token security

Tokens begin with sk-tuple- and do not expire.
Only the last four characters of each token are visible after creation.
You can create multiple tokens to give each integration its own credential, making it easy to revoke access for a single integration without affecting others.
Treat tokens like passwords. Do not commit them to source control or share them in plain text.

Notes

Only completed calls are returned (in-progress calls are excluded).
Calls are filtered by ended_at, not started_at.

Getting Started

Pairing with Tuple

Managing Your Account

Team Management

Application Preferences

Tuple CLI

Triggers

Troubleshooting

Endpoint

Authentication

Query parameters

Response

Rate limiting

Error responses

Example

Managing API tokens

Create a token

Revoke a token

Token security

Notes

​Endpoint

​Authentication

​Query parameters

​Response

​Pagination headers

​Rate limiting

​Error responses

​Example

​Managing API tokens

​Create a token

​Revoke a token

​Token security

​Notes

Endpoint

Authentication

Query parameters

Response

Pagination headers

Rate limiting

Error responses

Example

Managing API tokens

Create a token

Revoke a token

Token security

Notes