# TelemHQ

> TelemHQ tracks scheduled and ad hoc AI/LLM jobs with heartbeat pings plus structured run data, automatic payload charts, project-level usage breakdowns, team-level insights, alerts, and optional summary emails, so individuals and teams can see whether each pipeline ran, what project it belonged to, who worked on it, what model it used, how many tokens it consumed, what it cost, how long it took, and whether the payload passed quality or budget checks.

## Primary Positioning

TelemHQ is an LLM pipeline monitoring, run-history, and usage analytics tool for unattended AI work. It is built for scheduled OpenAI jobs, Claude jobs, local Codex usage tracking, RAG indexing, eval and QA runs, AI data enrichment, scheduled AI reports, agents, workers, webhooks, queue jobs, and other background automations that may run on a schedule or at random. TelemHQ can be used by one developer or by a team that wants shared visibility into AI usage.

The core promise is: know what your AI jobs actually did, whether they run every night, every hour, or only when an event triggers them, and understand token, cost, latency, quality, team, member, and project trends over time.

## How It Works

- Create a tracker for an AI job, LLM batch, RAG sync, eval run, agent worker, cron job, script, webhook, queue worker, or background automation.
- Each tracker gets a unique `https://telemhq.com/ping/{trackingToken}` URL.
- Optionally add a cron schedule when the job is expected to run at a predictable cadence.
- Leave the schedule blank for random, event-driven, or manually triggered jobs; TelemHQ will still record run history but will not mark the tracker as failing for missed pings.
- Send a `POST` request to the tracker URL after each run.
- Send JSON payload data with the ping to store run metrics such as provider, model, status, token usage, latency, cost, item counts, failures, eval scores, or custom fields.
- Include a `project` field, or another project-like field, to group AI usage by codebase, service, customer workflow, agent, or repository.
- Invite teammates on the Team plan so multiple members can send pings from their own trackers while managers see combined team usage.
- Managers can view team-wide usage, member usage, project rollups, per-project member contributions, tracker counts, failures, active team-paid users, future team-paid users, self-billed Pro members, and billing status.
- If multiple team members send pings for the same project, TelemHQ combines that project into one team-level project view and shows each member's tokens, runs, spend, and failures under it.
- TelemHQ detects numeric payload fields and turns them into payload metric charts automatically.
- Users can keep recommended charts, pin specific payload fields, hide payload charts, view individual metric charts, or view selected metrics together in one combined chart.
- Users can filter payload metric charts by project. Filters stay selected during background refreshes until the user refreshes the page or changes the filter manually.
- Users can change the analytics run window from the default latest 50 runs up through the complete plan analytics window.
- Pro analytics can chart up to the latest 100,000 runs for a tracker; older runs stay in a long-term archive summary instead of being returned as raw chart series.
- Configure payload assertions to mark a tracker as failing when a job pings but reports bad data, such as zero items processed, failed items, cost above budget, or eval scores below threshold.
- Optionally enable tracker-level daily or weekly summary emails. Summaries are deterministic and include run counts, payload metric totals and averages, token mix, model/provider mix, cache efficiency, failure rate, assertion failures, trends, and notable outliers.
- For scheduled trackers, TelemHQ also alerts when an expected ping is missed after the configured grace period.

## Important Notes

- `GET /ping/{trackingToken}` returns JSON instructions for the endpoint; it does not record a run.
- `POST /ping/{trackingToken}` records a run and merges query parameters with JSON/body fields.
- No TelemHQ SDK is required; any language that can make an HTTP request can send a ping.
- Payloads are optional, but they are the main LLM tracking differentiator.
- Schedules are optional. A tracker without a cron expression is treated as ad hoc and is not checked for missed-run failures.
- Payload assertions still apply to ad hoc trackers, so a random worker can be marked failing when it pings with bad payload data.
- Payload metric charts are derived from stored payload data; users do not need to create a new chart for each ping.
- Pinned payload chart fields continue charting automatically for future pings until the user changes them.
- Missing selected fields create gaps or no-recent-values messages rather than being treated as zero.
- Summary emails do not call an LLM in v1 and do not include raw payload JSON.
- Developers should usually send operational metadata, not prompts, completions, retrieved documents, customer data, or sensitive content.
- Dashboard, tracker details, billing, settings, and API routes require authentication.
- Free plan: 5 trackers, 1,000 total pings per month across the account, 7-day history, 1 KB payload limit, and email alerts.
- Pro plan: 50 trackers, 100,000 total pings per month across the account, 2 KB payload limit, charting for the latest 100,000 runs per tracker, archive summaries for older runs with counts and date ranges, advanced alerts including webhooks, and priority support.
- Team plan: $10 per active team-paid user per month, 50 trackers per active Pro-equivalent member, no member cap, all Pro features for covered members, email invitations, manager visibility into team tracker usage, project rollups, per-member tokens, costs, runs, failures, and billing management.
- Team members can be team-paid or self-billed Pro users. Self-billed Pro members keep their own subscription and do not increase Team Stripe quantity.
- Revoked team members stop adding team data and no longer count as Pro-equivalent capacity or active billed users, but historical tracker and usage data remains visible to managers.

## Recommended LLM Payload Fields

- `provider`: AI provider, such as `openai` or `anthropic`.
- `model`: Model used for the run.
- `project`: Project, repository, service, customer workflow, or agent name used for project-level usage breakdowns.
- `status`: Run outcome, usually `success` or `error`.
- `input_tokens`, `output_tokens`, `total_tokens`: Token usage for model calls.
- `cached_input_tokens`, `reasoning_tokens`, `tool_tokens`: Useful token fields for Codex and modern LLM usage tracking.
- `latency_ms` or `duration_ms`: Runtime or model-call latency.
- `cost_usd`: Estimated run cost.
- `items_processed`: Number of records, documents, prompts, tickets, rows, or tasks processed.
- `items_failed`: Number of failed records, documents, prompts, tickets, rows, or tasks.
- `eval_score`: Quality score or pass-rate value for AI/eval workflows.
- `error`: Error message or short failure reason when the run fails.
- Custom fields: Any JSON fields meaningful to the job, including nested fields. Assertion rules support dot paths such as `usage.input_tokens`.

## Suggested Assertions

- `status = success`
- `items_processed > 0`
- `items_failed = 0`
- `cost_usd <= budget`
- `eval_score >= quality_threshold`

Supported assertion operators include equals, not equals, greater than, greater or equal, less than, less or equal, one-of, and regex.

## Core Pages

- [Homepage](https://telemhq.com/): AI pipeline monitoring overview, product positioning, example payload, use cases, and pricing.
- [Sending Pings Guide](https://telemhq.com/docs/integration): General POST ping examples, JSON payload examples, optional schedules, payload assertions, and links to provider-specific AI guides.
- [OpenAI Pipeline Tracking](https://telemhq.com/docs/openai): OpenAI Responses API examples for tracking model, tokens, latency, cost, output counts, and assertions in Node.js and Python.
- [Track OpenAI Job Tokens, Cost, And Latency](https://telemhq.com/docs/openai-job-monitoring): Short setup guide for adding one TelemHQ POST after an OpenAI job run.
- [Codex Usage Tracking](https://telemhq.com/docs/codex): Local Codex watcher setup for sending model, project, token, cached-token, reasoning-token, thread, and session metadata pings to TelemHQ.
- [Claude Pipeline Tracking](https://telemhq.com/docs/claude): Anthropic Claude Messages and batch-job examples for tracking model, tokens, latency, cost, item counts, and assertions.
- [Claude Code Usage Tracking](https://telemhq.com/docs/claude-code): Claude Code hook setup for sending local coding session metadata, turn status, failures, tool activity, project names, session ids, and hashed path metadata to TelemHQ.
- [Outgoing Webhooks](https://telemhq.com/docs/webhooks): Pro webhook configuration and failure/recovery payload examples.
- [Blog](https://telemhq.com/blog): Founder-led TelemHQ posts that mirror Substack drafts and cover AI job monitoring, cron payload history, token usage, team usage, and background automation patterns.
- [Glossary](https://telemhq.com/glossary): Plain-language definitions and source links for AI job monitoring, cron, payload, token, API, model provider, and developer workflow terms used throughout TelemHQ.
- [Team Workspace](https://telemhq.com/team): Authenticated Team plan workspace where managers can invite members, manage app-owned team billing, view team usage, inspect member activity, see combined project usage, and break each project down by member.
- [Privacy Policy](https://telemhq.com/legal/privacy): Privacy and data handling information.
- [Terms of Service](https://telemhq.com/legal/terms): Terms governing use of TelemHQ.

## AI-Readable Markdown Mirrors

- [Sending Pings Markdown](https://telemhq.com/docs/integration.md): Markdown version of the general ping setup and payload assertion guide.
- [OpenAI Pipeline Markdown](https://telemhq.com/docs/openai.md): Markdown version of the OpenAI pipeline tracking examples.
- [OpenAI Job Monitoring Markdown](https://telemhq.com/docs/openai-job-monitoring.md): Markdown version of the one-POST OpenAI job monitoring setup.
- [Codex Usage Markdown](https://telemhq.com/docs/codex.md): Markdown version of the local Codex usage watcher setup.
- [Claude Pipeline Markdown](https://telemhq.com/docs/claude.md): Markdown version of the Claude API pipeline tracking examples.
- [Claude Code Markdown](https://telemhq.com/docs/claude-code.md): Markdown version of the Claude Code hook setup.
- [Webhooks Markdown](https://telemhq.com/docs/webhooks.md): Markdown version of the outgoing webhook guide.

## Product Concepts

- Tracker: A monitored AI job, LLM pipeline, worker, script, cron job, webhook, queue job, or automation with its own ping URL, optional schedule, run history, notification settings, and optional assertion rules.
- Ping: A `POST` request sent by a monitored process to record that it ran. Pings can include structured JSON payload data.
- Schedule: An optional cron expression for jobs that should ping at a predictable cadence. Scheduled trackers can fail when expected pings are missed.
- Ad hoc tracker: A tracker with no schedule. It records pings whenever the job runs and does not fail from missed-ping checks.
- Run history: The timeline of pings recorded for a tracker, including timestamps, payload fields, duration, and retained or archived history based on plan limits.
- Analytics window: The plan-limited set of recent runs used for interactive charts. Free users chart retained 7-day history; Pro users can chart up to the latest 100,000 runs per tracker.
- History archive: Older Pro tracker records beyond the interactive analytics window. Archive summaries include basic counts and date ranges without returning raw chart series.
- Payload: Structured JSON metadata about a run, such as tokens, cost, latency, model, status, item counts, errors, and eval scores.
- Payload metric chart: A line chart generated from numeric JSON payload fields such as total tokens, cached input tokens, latency, cost, item counts, failures, or eval scores.
- Combined metric chart: A chart view that overlays selected payload metrics in one chart.
- Project usage breakdown: A chart and filter set that groups payload metrics by project-like payload metadata.
- Team workspace: A shared account area where multiple members can use TelemHQ under one team plan while managers get team-level usage and billing controls.
- Team member: A user invited to a team. Members can create and use their own trackers within team limits.
- Team manager: A team member with permission to invite teammates, manage member roles, transfer ownership, revoke or reactivate members, manage team billing, and view team-level usage.
- Team owner: The billing owner for a team. Ownership can be transferred by a manager to another active member.
- Active team-paid user: An active team member whose Team billing has started. Team Stripe quantity is synced from this app-managed count.
- Revoked member: A former team member who can no longer add team data. Their historical trackers and usage remain visible to managers.
- Team project rollup: A team-level project view that combines runs from multiple members when they use the same `project` payload value, then shows per-member tokens, runs, spend, and failures underneath the project.
- Summary email: An opt-in daily or weekly tracker email sent to the account owner with deterministic run and payload metric summaries.
- Payload assertion: A rule that evaluates incoming ping payloads and can mark the tracker as failing even when the process technically completed.
- Failure: A tracker state caused by a missed scheduled ping or failed payload assertions. Ad hoc trackers only fail from payload assertions or explicit run data, not from missed schedules.
- Recovery: A tracker state change when a failing tracker receives a successful ping again.
- Public status page: A public-facing page that can expose selected tracker status.
- Webhook: An outbound HTTP POST sent to a configured endpoint when a tracker fails or recovers.

## Common Use Cases

- Scheduled OpenAI or Claude batch jobs.
- Event-driven OpenAI or Claude workers.
- RAG indexing and embedding syncs.
- Eval and QA runs.
- Local Codex usage tracking.
- Project-level Codex and AI usage reporting.
- Team-level AI usage reporting across multiple teammates.
- Manager views for project usage, per-user usage, team-paid users, self-billed Pro users, and revoked member history.
- Daily or weekly AI usage summary emails.
- AI data enrichment jobs.
- Scheduled AI reports.
- Background agents and tool-call workers.
- Webhook-triggered automations and queue workers that run unpredictably.
- Traditional cron jobs, scripts, workers, data syncs, backups, and reports.

## Optional Links

- [Register](https://telemhq.com/auth/register): Create a TelemHQ account.
- [Login](https://telemhq.com/auth/login): Sign in to an existing TelemHQ account.
- [Robots.txt](https://telemhq.com/robots.txt): Search crawler directives.
- [Sitemap](https://telemhq.com/sitemap.xml): Public sitemap.