Skip to main content
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

ParameterRequiredDescription
sinceYesISO 8601 datetime. Only returns calls that ended at or after this time.
untilNoISO 8601 datetime. Only returns calls that ended before this time. Defaults to now.
pageNoPage number for pagination. Defaults to 1.
per_pageNoNumber 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).
HeaderDescription
X-Total-CountTotal number of calls matching the query.
LinkStandard 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

StatusCause
401 UnauthorizedMissing or invalid Bearer token.
422 Unprocessable EntityMalformed since or until parameter (must be valid ISO 8601).
429 Too Many RequestsRate 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

1

Open the API tokens page

Go to your team management page.
2

Create a new token

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

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.