Analytics API reference

Account-owned datasets with principal RBAC. Write-key analytics event ingestion.

Published contracts: @socra/analytics-api@0.1.0.

Authenticated request and response

Use an Account access token with authorization for the dataset. Account-owned datasets use principal roles (admin, viewer or writer); Project IAM alone does not grant dataset access. /v1/events:batch uses a dataset write_key in its body; the authenticated dataset and managed-delivery paths have separate contracts below. Retention and cost depend on the current service terms.

This illustrative read uses an existing access token. Set ACCESS_TOKEN through your authorized credential provider; keep it out of source, logs and shared shell history. The identifiers and response below are fictional, validated against the published package. They are not a runtime execution receipt.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Accept: application/json' \
  'https://analytics.socra.cloud/v1/datasets?limit=1'

Example successful response body:

{
  "data": [
    {
      "id": "dataset_01m00000000000000000000000",
      "name": "Example dataset",
      "environment": "production",
      "retention_days": 90,
      "status": "active",
      "created_at": "2026-10-20T12:00:00.000Z",
      "updated_at": "2026-10-20T12:00:00.000Z",
      "account_id": "00000000-0000-4000-8000-000000000001",
      "roles": [
        "viewer"
      ]
    }
  ],
  "has_more": false
}

For body requests, send JSON with Content-Type: application/json and the exact body fields listed under the operation. Required scopes, when declared, appear with the operation. A token and a valid request shape do not replace the service's authorization rules.

Handle unsuccessful responses

Inspect the HTTP status and response body before taking another action. The published API client retains status, method, URL and body on APIError. It accepts a JSON error object with optional error, message, code and details fields; it also preserves a text or empty body. The method contracts below do not declare a complete per-operation error catalog.

An illustrative JSON error body (field names follow the client contract; the message is an example):

{
  "message": "The request was rejected. Check the status and service permissions."
}

• For 400 or another validation response, compare the named field, required fields, types, bounds and accepted values with this reference before correcting the request.
• For 401, obtain or refresh your token through the supported authorization path. Never paste a token into a bug report.
• For 403, stop and ask the resource owner to verify the intended principal, Account or Project, required permission and service enablement. An access denial is not evidence of a runtime defect.
• For 404, verify the exact resource identifier and Account or Project context with its owner; do not recreate a resource merely because a read failed.
• For 429, follow Retry-After if the service supplies it. These contracts specify no universal rate limit or retry interval.
• For a 5xx response or interrupted connection after a write, inspect supported resource state before retrying. The effect may be uncertain; automatic replay can duplicate work.

These are status-based troubleshooting steps, not a promise that each operation returns each status or the sample body. Preserve the exact status and redacted body when requesting help.