Skip to content

Convex realtime

Tables & indices

  • runs_live
  • Fields: id, projectId, experimentId?, provider, model, inputTokens, outputTokens, costUSD, costSource?, costEstimated?, latencyMs, status, errorCode?, promptHash?, promptPreview?, traceId?, createdAt, syncedToPg, metadata?
  • Indices: by_project_time, by_experiment_time, by_status_time, by_run_id, by_created_time
  • kpis_1m: per-minute aggregates by projectId, minuteTs
  • projects: with by_organization, by_organization_active
  • apiKeys: with by_project, by_organization, by_key_hash, by_project_active
  • entitlements: with by_org

See also: convex/schema.md

Functions

  • runs.ingestRun, runs.ingestRuns: insert run(s), schedule sync, idempotent by id (set from runId when provided).
  • runs.listRuns(projectId, sinceMs): recent runs for a project, capped at 500.
  • runs.listRunsByOrganization(organizationId, sinceMs): scans time index and filters by project membership.
  • runs.getById(runId): lookup by by_run_id.
  • runs.markSynced(runId): internal mutation to set syncedToPg=true.
  • runsActions.internalSyncToPg(runId): internal action to POST to /api/internal/pg-sync with HMAC.
  • kpis.rollup1m: internal mutation; Convex cron every minute.
  • projects.create, projects.listByOrganization, projects.getById, projects.update, projects.archive.
  • apiKeys.create, apiKeys.listByProject, apiKeys.listByOrganization, apiKeys.validateKey, apiKeys.recordUsage, apiKeys.revoke, apiKeys.update.

See also: convex/runs.md, convex/runsActions.md, convex/kpis.md, ../03-architecture.md, ../06-frontend.md

Subscriptions in UI

  • /dashboard: useQuery(api.runs.listRunsByOrganization, { organizationId, sinceMs })
  • /runs: useQuery(api.runs.listRuns, { projectId, sinceMs })
  • /settings: API keys via api.apiKeys.listByProject
  • /projects: api.projects.listByOrganization, api.projects.getById

Cleanup & retention

  • TTL for runs_live not yet configured. TODO: Add periodic cleanup/archival.