# Connections

> The API operations about connections, each with its input, its output and an example.

The operations about connections. Each one is a `POST` with a JSON object as its body: [Making a request](/docs/api#start) has the rules they share.

## Ad platform connections

`POST /api/v1/connections.list` · Read

The ad platform accounts connected to one site, oldest first: for each, the platform, the account name, its status, when spend was last synced and the last error. Get the siteId from sites.list first. Spend is synced from each active connection every hour. A status of needs_reauth means the sign-in was revoked or expired and a person must sign in again in the dashboard; error means the last syncs failed and lastError says why; paused connections are not synced. lastSyncAt is an ISO 8601 time in UTC, or null before the first sync. The answer never carries a sign-in token. It holds an empty list for a site with no connection, and it still answers while the workspace's dashboards are locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string | required | The site id, from sites.list. |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `connections` | array of object | always | The ad accounts connected to the site, oldest first: id, platform, accountName, status, lastSyncAt (ISO time or null) and lastError (text or null). No sign-in token is ever included. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/connections.list \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'
```

**CLI**

```bash
clearsaga connections list --input '{"siteId":"site_abc123def456"}'
```

**MCP**

```text
Tool: connections_list
Arguments: {"siteId":"site_abc123def456"}
```

Run `clearsaga help connections list` for one flag per field.