Analytics

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.

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);

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

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.

Read deployment statistics

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

curl "$OPENSHIP_URL/api/analytics/deployments?projectId=proj_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

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.

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

curl "$OPENSHIP_URL/api/analytics/resources?projectId=proj_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

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

Live usage

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

curl -N "$OPENSHIP_URL/api/analytics/usage/stream?projectId=proj_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

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

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

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

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.

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

curl "$OPENSHIP_URL/api/analytics/server/srv_123?domain=app.example.com" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

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

Operations