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

# Connection history

> The timeline of when each number was linked and unlinked from an instance

This page documents the **connection history**, an auditable timeline of when each WhatsApp number was linked (connected) and unlinked (disconnected) from an instance. Use it to follow and confirm which number was connected at each moment, handy when reviewing a billed period with transparency, with the record in hand.

## Query the history

**`GET /api/account/connections?number=<jid>&instance=<id>&from=<rfc3339>&to=<rfc3339>&limit=<n>`**

Returns the account's link and unlink events, most recent first. Authenticate with the account **TokenAccount**, or with the global token passing `?account=<account-name>`. All filters are optional: with none, you get the account's most recent events.

<ParamField query="number" type="string">
  Filters by a specific number. Use the exact JID, e.g. `5511999998888@s.whatsapp.net`.
</ParamField>

<ParamField query="instance" type="string">
  Filters by a specific instance. Use the `instanceId` that appears in the events themselves.
</ParamField>

<ParamField query="from" type="string">
  Start of the window, in RFC3339. Without it, there is no lower bound.
</ParamField>

<ParamField query="to" type="string">
  End of the window, in RFC3339. Without it, there is no upper bound.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of events to return. Default `200`. Values outside the `1` to `1000` range also use `200`.
</ParamField>

<ParamField query="account" type="string">
  Account name. Required only when you use the global token.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://ryzeapi.cloud/api/account/connections?number=5511999998888@s.whatsapp.net&limit=50" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    number: "5511999998888@s.whatsapp.net",
    limit: "50"
  });

  await fetch(`https://ryzeapi.cloud/api/account/connections?${params}`, {
    headers: { "token": process.env.Token_Account }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/account/connections",
      headers={"token": os.environ["Token_Account"]},
      params={"number": "5511999998888@s.whatsapp.net", "limit": 50}
  )
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "events": [
    {
      "instanceId": "9f1c2b3a-7d4e-4a1b-9c2d-3e4f5a6b7c8d",
      "instanceName": "client-acme",
      "numberJid": "5511999998888@s.whatsapp.net",
      "event": "unlinked",
      "at": "2026-08-20T09:05:00Z"
    },
    {
      "instanceId": "9f1c2b3a-7d4e-4a1b-9c2d-3e4f5a6b7c8d",
      "instanceName": "client-acme",
      "numberJid": "5511999998888@s.whatsapp.net",
      "event": "linked",
      "at": "2026-08-01T12:30:00Z"
    }
  ]
}
```

## Response fields

<ResponseField name="events" type="array">
  The connection events, most recent first. A deleted instance keeps its events, with the name and number it had, because the record survives deletion.

  <Expandable title="fields of each event">
    <ResponseField name="instanceId" type="string">
      Instance identifier. Use this value in the `instance` filter.
    </ResponseField>

    <ResponseField name="instanceName" type="string">
      Instance name at the time of the event.
    </ResponseField>

    <ResponseField name="numberJid" type="string">
      The WhatsApp number (JID) involved in the event.
    </ResponseField>

    <ResponseField name="event" type="string">
      `linked` when the number was linked (connection) or `unlinked` when it was unlinked (disconnection).
    </ResponseField>

    <ResponseField name="at" type="string">
      When the event happened, in RFC3339 (UTC).
    </ResponseField>
  </Expandable>
</ResponseField>

## Next

<CardGroup cols={2}>
  <Card title="Usage statement" icon="receipt" href="/en/enterprise/statement">
    The itemized invoice for the period, instance by instance.
  </Card>

  <Card title="Enterprise webhooks" icon="webhook" href="/en/enterprise/webhooks">
    React to each state change by event.
  </Card>
</CardGroup>