Skip to main content
Some teams want to integrate Tuple call data with tools like DX and Jellyfish. To that end, we offer a private usage API. To get access, you can 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-...
We’ll create your team’s token when you contact us for access. You can also ask us to rotate your key for you.

​
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://app.tuple.app/api/v2/call_usage?since=2026-03-01T00:00:00Z&until=2026-03-31T00:00:00Z"

​
Notes

  • Only completed calls are returned (in-progress calls are excluded).
  • Calls are filtered by ended_at, not started_at.
  • Tokens do not expire. Rotation is manual.