Logs

Ship your application's log events to Helmdesk and it becomes your error watchdog: events are grouped into issues by fingerprint, the Log Watch agentemails you when a new error appears or a known one keeps recurring, and your AI tools can query everything over the API. It is not a full observability platform — it is the "tell me when something is wrong" layer a small team actually reads.

Ship events

Send batches of up to 100 events to POST /api/v1/logs with an API key holding the logs:write scope (there is a Log shipper preset when creating keys). Levels are debug, info, warn, error, and fatal; metadata is any JSON object up to 8 KB.

import { HelmdeskClient } from '@helmdesk/sdk'

const helmdesk = new HelmdeskClient({ apiKey: process.env.HELMDESK_API_KEY! })

// Fire-and-forget from your error paths — don't await on the hot path.
void helmdesk.logs.write([
  {
    level: 'error',
    scope: 'checkout',
    message: 'Payment failed: card declined',
    metadata: { orderId: 'ORD-4821', provider: 'stripe' },
  },
])

Or with plain fetch:

await fetch('https://helmdesk.dev/api/v1/logs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.HELMDESK_API_KEY}`,
  },
  body: JSON.stringify({
    events: [
      { level: 'error', scope: 'worker', message: 'Job import-users failed: timeout' },
    ],
  }),
})

Error grouping (fingerprints)

Every event is fingerprinted from its level, scope, and normalized message — ids, emails, timestamps, and numbers are stripped first, so Order 4821 failed and Order 5133 failed land in the same issue. Issues track first/last seen, a running count, and a status (open → acknowledged → resolved). A resolved issue that recurs is automatically reopened as a regression.

The Log Watch agent

Enable Log Watchon the project's Agents page and it checks your live error and fatal issues every 15 minutes. It alerts — an item in the Agents Activity inbox plus an email to the team (opt-out per member under Notifications) — when either:

• a new error fingerprint appears for the first time, or
• a known error recurspast your configured threshold inside the detection window (both tunable in the agent's config).

The same issue re-alerts at most once every 24 hours, at most 5 alerts per sweep, and acknowledged or resolved issues stay quiet. Sandbox logs never trigger the agent.

Query logs

Both endpoints require the logs:read scope — ideal for an AI assistant that checks your errors every morning.

// Raw events, newest first
const { logs, total } = await helmdesk.logs.list({
  level: 'error,fatal',
  search: 'timeout',
  limit: 50,
})

// Grouped issues
const { issues } = await helmdesk.logs.issues({ status: 'open' })
for (const issue of issues) {
  console.log(`${issue.level} ×${issue.eventCount}: ${issue.sampleMessage}`)
}

Retention & quotas

Live log events are pruned automatically after your plan's retention window; issues age out when they stop recurring. Monthly event quotas apply to live events only.

Sandbox events (shipped with an sk_sandbox_… key) are quota-exempt and kept for 3 days on every plan — see Sandbox.

Limits

• Up to 100 events per request.
• Messages up to 4,000 characters; metadata up to 8 KB per event.
• Standard API rate limit: 100 requests/minute per key — batch your events.