API Documentation

Create a new user account and organization. Open to anyone when no users exist (first-user bootstrap). Existing users can invite new members.

Request

{
  "email": "[email protected]",
  "password": "securepassword",
  "name": "Jane Doe",
  "orgName": "Acme Inc"
}

Response 201

{
  "success": true,
  "user": { "id": "...", "email": "[email protected]", "name": "Jane Doe" },
  "org": { "id": "...", "name": "Acme Inc", "slug": "acme-inc" },
  "project": { "id": "...", "name": "Default", "slug": "default" },
  "apiKey": "sw_a1b2c3..."
}

Authenticate with email and password. Sets an HttpOnly session cookie valid for 24 hours.

{
  "email": "[email protected]",
  "password": "securepassword"
}

Invalidates the current session and clears the cookie.

Returns the authenticated user's profile and their organizations with projects.

{
  "user": { "id": "...", "email": "[email protected]", "name": "Jane Doe" },
  "orgs": [
    {
      "id": "...", "name": "Acme Inc", "slug": "acme-inc", "role": "owner",
      "projects": [{ "id": "...", "name": "Default", "slug": "default" }]
    }
  ]
}

List all members of the organization with their roles and join dates.

Invite a user to the organization. If the email doesn't match an existing user, a new account is created with a temporary password.

Request

{ "email": "...", "name": "Jane Doe", "role": "member" }

Response 201

{ "user_id": "...", "temp_password": "abc123..." }

Update a member's role. Only owners can promote to owner or admin.

{ "role": "admin" }

Remove a member from the organization. Cannot remove yourself.

Generate a new temporary password for a member.

{ "temp_password": "abc123..." }

List all projects in the organization.

Create a new project.

{ "name": "Mobile App" }

{ "id": "...", "name": "Mobile App", "slug": "mobile-app" }

Rename a project.

{ "name": "New Name" }

Delete a project and all its data. Cannot delete the last project in an org.

Submit a batch of log events. Max 50 events per request.

Request

{
  "events": [
    {
      "timestamp": 1709312400000,
      "level": "error",
      "type": "crash",
      "message": "NullPointerException in UserService",
      "service": "auth-worker",
      "environment": "production",
      "user_id": "user_123",
      "session_id": "sess_abc",
      "trace_id": "abc123",
      "span_id": "span001",
      "metadata": { "stack_trace": "...", "app_version": "2.1.0" }
    }
  ]
}

Fields

Response 202

{ "status": 202, "inserted": 1 }

Search and filter log events with pagination. Automatically queries both D1 hot storage and R2 cold archive when from is older than 24 hours.

Query Parameters

{ "results": [ { ...event } ], "total": 142 }

Fetch a single log event by ID. Returns 404 if not found.

Returns distinct service names. Also available: /device-types and /environments.

{ "services": ["auth-worker", "billing-api", "flutter-app"] }

Get value counts for key fields (level, type, service, environment, device_type), scoped to the same filters as the logs endpoint. Powers the faceted sidebar in Log Explorer.

Accepts all the same query parameters as the logs endpoint.

{
  "facets": {
    "level":  [{ "value": "error", "count": 142 }, { "value": "warn", "count": 89 }],
    "type":   [{ "value": "crash", "count": 23 }],
    "service": [ ... ],
    "environment": [ ... ],
    "device_type": [ ... ]
  }
}

Group logs by normalizing variable parts of messages (IDs, numbers, UUIDs) into placeholders. Useful for identifying recurring issues without noise.

{
  "patterns": [
    {
      "pattern": "NullPointerException in {id}",
      "level": "error",
      "type": "crash",
      "count": 47,
      "sample": "NullPointerException in UserService user_abc123",
      "services": ["auth-worker", "billing-api"],
      "first_seen": 1709300000000,
      "last_seen":  1709312400000
    }
  ]
}

Generate a plain-English summary of recent log activity for a given time window. Aggregates event counts, top services, and error patterns — then asks Workers AI to summarize. The result is stored for 7 days.

Request

{ "minutes": 15 }

Valid values: 5, 15, 30, 60. Defaults to 15 if omitted.

Response 200

{
  "id": "01JNXYZ...",
  "summary_text": "In the last 15 minutes, 142 events were logged...",
  "error_count": 12,
  "warn_count": 34,
  "event_count": 142,
  "created_at": 1741234567890,
  "time_window_minutes": 15
}

Returns the most recent stored AI summary for the project, or null if none has been generated yet.

{ "summary": { ...summary row } | null }

List persistent log patterns stored by the background cron. Patterns are normalized (IDs, numbers, and UUIDs replaced with placeholders) and deduplicated by hash. Updated every 5 minutes automatically.

Query Parameters

Response

{
  "patterns": [
    {
      "id": "...",
      "normalized_message": "Connection timeout after {num}ms",
      "level": "error",
      "service": "api",
      "first_seen": 1741230000000,
      "last_seen": 1741234500000,
      "occurrence_count": 47,
      "is_new": false
    }
  ]
}

List all saved lenses ordered by sort_order.

{
  "lenses": [
    {
      "id": "01HQXYZ...", "name": "Prod Errors",
      "filters": "{"level":"error","env":"production"}",
      "color": "red", "sort_order": 0
    }
  ]
}

Create a new lens. Color options: accent, red, orange, yellow, green, blue.

{ "name": "Prod Errors", "filters": "{...}", "color": "red" }

Update name, filters, color, or sort order. All fields optional.

Delete a lens by ID.

Submit a batch of spans. Max 50 per request. The trace row is derived automatically from the root span (no parent_span_id).

Request

{
  "spans": [
    {
      "trace_id": "abc123",
      "span_id": "span001",
      "parent_span_id": null,
      "name": "HTTP GET /api/users",
      "service": "api-gateway",
      "start_time": 1709312400000,
      "end_time":   1709312400142,
      "status": "ok",
      "attributes": {
        "http.method": "GET",
        "http.url": "/api/users",
        "http.status_code": 200
      },
      "environment": "production"
    },
    {
      "trace_id": "abc123",
      "span_id": "span002",
      "parent_span_id": "span001",
      "name": "DB SELECT users",
      "service": "db-service",
      "start_time": 1709312400020,
      "end_time":   1709312400100,
      "status": "ok"
    }
  ]
}

Span Fields

Response 202

{ "status": 202, "inserted": 2 }

Submit spans in OTLP/JSON format. Service name is extracted from resource.attributes["service.name"]. OTel status code 2 maps to error.

SDK Configuration

// OpenTelemetry JS / Python / Go / etc.
endpoint: "https://api.scrywatch.com/api/traces/otlp"
headers:  { "Authorization": "Bearer YOUR_API_KEY" }
protocol: "http/json"

Example Payload

{
  "resourceSpans": [{
    "resource": {
      "attributes": [{ "key": "service.name", "value": { "stringValue": "api-gateway" } }]
    },
    "scopeSpans": [{
      "spans": [{
        "traceId": "abc123",
        "spanId": "span001",
        "name": "HTTP GET /api/users",
        "startTimeUnixNano": "1709312400000000000",
        "endTimeUnixNano":   "1709312400142000000",
        "status": { "code": 1 }
      }]
    }]
  }]
}

List sampled traces. Only traces that passed tail-based sampling are returned.

Query Parameters

{
  "traces": [
    {
      "id": "abc123", "name": "HTTP GET /api/users",
      "service": "api-gateway", "start_time": 1709312400000,
      "duration_ms": 142, "status": "ok", "span_count": 4
    }
  ],
  "total": 87
}

Fetch a single trace with all its spans for rendering a waterfall view.

{
  "trace": { "id": "abc123", "name": "...", "duration_ms": 142, "status": "ok", ... },
  "spans": [
    { "id": "span001", "parent_span_id": null, "name": "HTTP GET /api/users", "duration_ms": 142, ... },
    { "id": "span002", "parent_span_id": "span001", "name": "DB SELECT users", "duration_ms": 80, ... }
  ]
}

Per-service throughput and latency metrics derived from sampled traces. Defaults to the last hour.

Query Parameters

from and to timestamps in ms.

{
  "services": [
    { "service": "api-gateway", "request_count": 1204, "error_count": 12, "p50_ms": 45, "p95_ms": 320 },
    { "service": "db-service",  "request_count": 987,  "error_count": 0,  "p50_ms": 8,  "p95_ms": 42  }
  ]
}

Event counts grouped by level, type, and hour. Defaults to the last 24 hours. Accepts from and to ms timestamps.

{
  "stats": [{ "level": "error", "type": "crash", "count": 12, "hour": 1709308800000 }],
  "from": 1709226000000,
  "to":   1709312400000
}

List unique sessions with event counts and severity breakdowns, ordered by most recent activity.

Query Parameters

limit (default 50, max 200), offset, environment.

{
  "sessions": [
    {
      "session_id": "sess_abc", "event_count": 47,
      "first_event": 1709300000000, "last_event": 1709312400000,
      "error_count": 3, "warn_count": 7, "crash_count": 1
    }
  ]
}

List all alert rules.

{
  "rules": [
    {
      "id": "...", "name": "High Error Rate",
      "condition_field": "level", "condition_value": "error",
      "threshold": 10, "window_minutes": 5, "cooldown_minutes": 15,
      "notify_type": "webhook", "webhook_url": "https://hooks.slack.com/...",
      "notify_email": null, "enabled": true
    }
  ]
}

Create a new alert rule. Use condition_field + condition_value to match against any log field.

Fields

Example — webhook on all errors

{
  "name": "High Error Rate",
  "condition_field": "level",
  "condition_value": "error",
  "threshold": 10,
  "window_minutes": 5,
  "notify_type": "webhook",
  "webhook_url": "https://hooks.slack.com/..."
}

Example — email on crashes from auth service

{
  "name": "Auth Crashes",
  "condition_field": "service",
  "condition_value": "auth-worker",
  "threshold": 1,
  "window_minutes": 15,
  "notify_type": "email",
  "notify_email": "[email protected]"
}

Update any alert rule field. All fields optional. Use enabled: false to pause a rule without deleting it.

Delete an alert rule.

Recent alert firings with timestamps, matched event count, and webhook delivery status.

Retrieve events from R2 cold storage by date. All log filters work identically against the archive.

Query Parameters

Real-time log streaming via WebSocket. Events are broadcast as JSON arrays as they are ingested.

const ws = new WebSocket(
  'wss://api.scrywatch.com/api/orgs/acme-inc/projects/default/ws/tail'
);
ws.onmessage = (e) => {
  const events = JSON.parse(e.data);
  console.log('Live events:', events);
};

Get or update the authenticated user's name and password.

List API keys (masked) or create a new one. The full key is returned only once — store it immediately.

// POST request
{ "name": "Production Key" }

// POST response (201)
{ "id": "...", "key": "sw_a1b2c3d4e5f6...", "name": "Production Key" }

Revoke an API key immediately.

Danger Zone. Permanently deletes all log events from hot storage. Archived R2 data is not affected.