# Analytics
URL: https://synquic.tech/docs/api/analytics.md

Read project traffic, deployment statistics, and resource usage.

Analytics report traffic, deployment outcomes, and runtime usage for resources the caller can access.
Project methods take a project ID in the SDK; REST uses `?projectId=`. Server methods take a server ID.

## Read request traffic

`overview` returns the cumulative summary and time-series periods together. Use `summary` or `periods`
when you only need one. `geo` adds geographic, path, and status-code breakdowns where available.

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
const traffic = await ship.analytics.overview("proj_123", {
  from: "2026-09-01T00:00:00Z",
  to: "2026-09-02T00:00:00Z",
});
console.log(traffic.summary, traffic.periods);
```

</Tab>
<Tab value="REST API">

```bash
curl "$SYNQ_URL/api/analytics/overview?projectId=proj_123&from=2026-09-01T00:00:00Z&to=2026-09-02T00:00:00Z" \
  -H "Authorization: Bearer $SYNQ_TOKEN"
```

</Tab>
</Tabs>

| Input | Applies to | Use |
| --- | --- | --- |
| `domain` | Summary, periods, overview, and geo | Limit results to one tracked hostname. |
| `from`, `to` | Periods, overview, and geo | Ordered ISO date range, at most 366 days. |

The project ID is required. An inaccessible or missing project is not included in results. Fixed
organization scopes do not forward through an owner's Cloud link; see [Cloud compatibility](/docs/api/sdk/compatibility#cloud).

## Read deployment statistics

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
const stats = await ship.analytics.deploymentStats("proj_123");
console.log(stats.successfulDeployments, stats.failedDeployments);
```

</Tab>
<Tab value="REST API">

```bash
curl "$SYNQ_URL/api/analytics/deployments?projectId=proj_123" \
  -H "Authorization: Bearer $SYNQ_TOKEN"
```

</Tab>
</Tabs>

Statistics include totals, success and failure counts, average build duration, and daily counts.
`dashboard()` returns project and deployment counts for the caller's organization.

## Read runtime usage

`resources` returns an aggregate plus per-service usage, capacity, timestamp, and a `supported` flag.
`usage` and `containerInfo` read the active runtime and can return `null` when it is unavailable.

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
const usage = await ship.analytics.resources("proj_123");
console.log(usage.supported, usage.overall, usage.services);
```

</Tab>
<Tab value="REST API">

```bash
curl "$SYNQ_URL/api/analytics/resources?projectId=proj_123" \
  -H "Authorization: Bearer $SYNQ_TOKEN"
```

</Tab>
</Tabs>

Use `usageHistory(projectId, { from, to, serviceKey })` for time buckets. All three filters are optional;
the result reports its `granularityMinutes` and selected `serviceKey`.

### Live usage

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
for await (const event of ship.analytics.streamUsage("proj_123", {
  signal: AbortSignal.timeout(30_000),
})) {
  console.log(event);
}
```

</Tab>
<Tab value="REST API">

```bash
curl -N "$SYNQ_URL/api/analytics/usage/stream?projectId=proj_123" \
  -H "Authorization: Bearer $SYNQ_TOKEN"
```

</Tab>
</Tabs>

The REST endpoint returns Server-Sent Events. An active deployment with a running container is required.
Pass an abort signal or stop iteration to close an SDK stream.

## Control path collection

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
await ship.analytics.setPathsCollection("proj_123", { enabled: true });
```

</Tab>
<Tab value="REST API">

```bash
curl -X POST "$SYNQ_URL/api/analytics/paths-collection/proj_123" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
```

</Tab>
</Tabs>

This changes collection settings and requires write access. Other analytics methods read data.

## Server analytics

Server analytics require `server:read` access and a tracked `domain`. Persisted buckets and daily geo
data remain readable when a server is offline; live analytics require a reachable management API.

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
const buckets = await ship.analytics.serverBuckets("srv_123", { domain: "app.example.com" });
console.log(buckets);
```

</Tab>
<Tab value="REST API">

```bash
curl "$SYNQ_URL/api/analytics/server/srv_123?domain=app.example.com" \
  -H "Authorization: Bearer $SYNQ_TOKEN"
```

</Tab>
</Tabs>

| Method | Additional input | Result |
| --- | --- | --- |
| `serverBuckets` | Optional `from`, `to` | Persisted minute buckets; range values accept ISO timestamps or epoch minutes. |
| `serverGeo` | Optional `day` in `YYYYMMDD` format | Daily country totals. |
| `serverLive` | None | Live edge analytics. |

Every method above also requires `domain`. Missing domain returns `400`; an unreachable live source can
return `502`.

## Operations

{/* api-operations:start */}

| Operation | SDK | REST API |
| --- | --- | --- |
| Stream current resource usage. | `analytics.streamUsage(projectId, options?)` | `GET /api/analytics/usage/stream`<br />`analytics:read` |
| Read summary statistics for the selected scope and period. | `analytics.summary(id, input?)` | `GET /api/analytics`<br />`analytics:read` |
| List supported analytics periods. | `analytics.periods(id, input?)` | `GET /api/analytics/periods`<br />`analytics:read` |
| Read aggregate traffic and application analytics. | `analytics.overview(id, input?)` | `GET /api/analytics/overview`<br />`analytics:read` |
| Read geographic traffic statistics. | `analytics.geo(id, input?)` | `GET /api/analytics/geo`<br />`analytics:read` |
| Read deployment outcome statistics. | `analytics.deploymentStats(id)` | `GET /api/analytics/deployments`<br />`analytics:read` |
| Read current workload resource usage. | `analytics.usage(id)` | `GET /api/analytics/usage`<br />`analytics:read` |
| Read analytics runtime/container information. | `analytics.containerInfo(id)` | `GET /api/analytics/container`<br />`analytics:read` |
| Read configured resource allocations. | `analytics.resources(id)` | `GET /api/analytics/resources`<br />`analytics:read` |
| Read historical resource usage. | `analytics.usageHistory(id, input?)` | `GET /api/analytics/usage/history`<br />`analytics:read` |
| Enable or disable request-path collection. | `analytics.setPathsCollection(id, input)` | `POST /api/analytics/paths-collection/:projectId`<br />`project:write` |
| Read server traffic buckets. | `analytics.serverBuckets(id, input)` | `GET /api/analytics/server/:serverId`<br />`server:read` |
| Read geographic server-request statistics. | `analytics.serverGeo(id, input)` | `GET /api/analytics/server/:serverId/geo`<br />`server:read` |
| Read current server traffic data. | `analytics.serverLive(id, input)` | `GET /api/analytics/server/:serverId/live`<br />`server:read` |
| Read the analytics dashboard aggregate. | `analytics.dashboard()` | `GET /api/analytics/dashboard`<br />`analytics:read` |
| Read a project's request traffic over a period: requests/sec, bandwidth, status classes, error rate and latency percentiles. | `analytics.traffic(id, input?)` | `GET /api/analytics/traffic`<br />`analytics:read` |
| Read a project's live traffic: requests in flight, requests/sec, bandwidth and error rate over the last minute. | `analytics.trafficLive(id, input?)` | `GET /api/analytics/traffic/live`<br />`analytics:read` |
| Read every server's current CPU, memory and disk with 24h sparklines. | `analytics.serverMetricsOverview()` | `GET /api/analytics/servers/metrics`<br />`analytics:read` |
| Read every server's live traffic headline. | `analytics.serverTrafficOverview()` | `GET /api/analytics/servers/traffic`<br />`analytics:read` |
| Read request traffic for every domain a server routes over a period. | `analytics.serverTraffic(id, input?)` | `GET /api/analytics/server/:serverId/traffic`<br />`server:read` |
| Read a server's live traffic, including requests in flight and connection counts. | `analytics.serverTrafficLive(id)` | `GET /api/analytics/server/:serverId/traffic/live`<br />`server:read` |
| Read a server's CPU, memory, disk, load and network history. | `analytics.serverMetrics(id, input?)` | `GET /api/analytics/server/:serverId/metrics`<br />`server:read` |
| Read a server's CPU, memory and disk alert thresholds. | `analytics.serverAlertThresholds(id)` | `GET /api/analytics/server/:serverId/alert-thresholds`<br />`server:read` |
| Update a server's CPU, memory and disk alert thresholds. | `analytics.setServerAlertThresholds(id, input)` | `PATCH /api/analytics/server/:serverId/alert-thresholds`<br />`server:write` |

{/* api-operations:end */}