> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuple.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage API (alpha)

> Access Tuple call data programmatically and manage API tokens from the dashboard.

Some teams want to integrate Tuple call data with tools like [DX](https://getdx.com/) and Jellyfish. To that end, we offer a usage API. To get access, [reach out to support](mailto:support@tuple.app).

## 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](#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).

```json theme={null}
[
  {
    "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)](https://datatracker.ietf.org/doc/html/rfc8288).

| **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

```bash theme={null}
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

<Steps>
  <Step title="Open the API tokens page">
    Go to your [team management page](https://production.tuple.app/team_management/api_tokens).
  </Step>

  <Step title="Create a new token">
    Click **Create token** and give it a descriptive name (for example, "DX integration" or "Jellyfish sync").
  </Step>

  <Step title="Copy the token">
    Copy the token immediately after creation. The full token is only shown once and cannot be retrieved later.
  </Step>
</Steps>

### 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`.