Runtime telemetry

Status: Normative.

Runtime telemetry records bounded lifecycle, configuration, asset, rendering, interaction, performance, and error activity for deployed Expanders, Signature, and Compositor clients. It is intended for integration debugging and operational support, not for storing product configuration state.

Endpoints and permissions

Use x-vertcie-key for both operations. A workspace session is not accepted as a substitute for an API key on these endpoints. Browser ingestion requires an exact allowed Origin. Reading follows the key's client policy: server keys are originless and browser keys require an allowed Origin.

telemetry:read is deliberately separate from runtime:read. Grant it only to integrations that need operational visibility.

Read events

GET /api/v1/runtime-events?publishedFileId=PUBLISHED_FILE_ID&severity=error&limit=50 HTTP/1.1
Host: YOUR_VERTCIE_ENDPOINT
x-vertcie-key: YOUR_API_KEY
x-request-id: runtime-errors-0001

The API always restricts results to events generated by the calling API key. Events associated with a Board are returned only while that key retains an active grant for the Board.

Query parameters

Filters are combined. Invalid dates, identifiers, limits, ordering values, or cursors return invalid_request.

Success response

{
  "ok": true,
  "data": {
    "events": [
      {
        "keyId": "key_record_identifier",
        "boardId": "board_identifier",
        "publishedFileId": "published_file_identifier",
        "revision": 4,
        "schemaVersion": 1,
        "eventId": "event_identifier",
        "sessionId": "session_identifier",
        "sequence": 18,
        "eventName": "configuration-resolved",
        "category": "configuration",
        "severity": "info",
        "outcome": "succeeded",
        "client": "compositor-expanders",
        "runtimeVersion": "0.3.3",
        "sceneId": "planning-study",
        "objectId": "lounge-1",
        "durationMs": 42,
        "message": null,
        "metadata": {
          "materialCount": 4,
          "visibleMeshCount": 12
        },
        "origin": "https://customer.example",
        "occurredAt": "2026-09-06T12:00:00.000Z",
        "receivedAt": "2026-09-06T12:00:00.250Z"
      }
    ]
  },
  "meta": {
    "requestId": "runtime-errors-0001",
    "nextCursor": "OPAQUE_NEXT_CURSOR"
  }
}

When meta.nextCursor is absent, no later page is available. Treat cursors as opaque and do not parse, modify, or persist them longer than the paging operation.

Submit events

The supported browser runtimes submit telemetry automatically. Custom runtime clients may use the same endpoint when they conform to schema version 1.

POST /api/v1/runtime-events HTTP/1.1
Host: YOUR_VERTCIE_ENDPOINT
Content-Type: application/json
Origin: https://customer.example
x-vertcie-key: YOUR_BROWSER_API_KEY

{
  "events": [
    {
      "schemaVersion": 1,
      "eventId": "event_identifier",
      "sessionId": "session_identifier",
      "sequence": 1,
      "eventName": "runtime-ready",
      "category": "lifecycle",
      "severity": "info",
      "outcome": "succeeded",
      "client": "expanders",
      "runtimeVersion": "0.1.96",
      "publishedFileId": "published_file_identifier",
      "revision": 4,
      "durationMs": 810,
      "metadata": {
        "assetCount": 14
      },
      "occurredAt": "2026-09-06T12:00:00.000Z"
    }
  ]
}

A batch contains 1–50 events and the complete body may not exceed 64,000 bytes. The API returns 202 Accepted with the accepted count and event IDs. Delivery is diagnostic and must never block or change runtime behavior.

Event identity and ordering

eventId is unique within the calling key and supports warehouse deduplication. sessionId + sequence provides runtime-session ordering. publishedFileId + revision identifies product content. Compositor events add sceneId + objectId so activity can be traced to one product within a multi-product scene.

The server derives API key, Organization, Board, and publication authorization. Client-supplied ownership fields are ignored.

Data safety and retention

Raw API keys, authorization and cookie values, passwords, tokens, full signatures, selections, configurations, signed URL query strings, and unbounded exception stacks are removed or rejected. Messages and nested metadata are bounded and sanitized again when read.

Detailed searchable events are retained for 30 days. Revoking a key stops new access immediately; normal retention still applies to the historical incident record. Longer-lived warehouse data follows the platform retention and tenant deletion policy and does not expose detailed session data through this API.

Error handling

Use X-Request-ID to correlate an API error with operational support. Do not retry 400, 401, or 403 unchanged. Retry 429 after the supplied delay and use bounded exponential backoff for 503.