Skip to main content
The GainTrace API lets you read your workspace’s customer data and push product-usage events, metric events, and signals into GainTrace. Ingested events flow into health scores, signals, and activation.

​
Base URL

https://app.gaintrace.com/api/v1
Every request is authenticated with a Bearer API key and scoped to a single workspace. Requests and responses are JSON.

​
What you can do

  • Accounts — list your workspace’s accounts with health, ARR, plan, and owner.
  • Signals — read open signals, or record your own against an account.
  • Product events — push Segment-style usage events that feed health, signals, and activation.
  • Metric events — push typed, idempotent events into the metrics engine.
See the API reference tab for every endpoint, request, and response.

​
Response format

List endpoints return a data array and a meta object: 
{
  "data": [],
  "meta": { "limit": 50, "offset": 0, "count": 50 }
}
Errors return an error string, sometimes with detail or code: 
{ "error": "Insufficient scope: read:companies required" }

​
Conventions

  • Pagination — limit (default 50, max 100) and offset on list endpoints.
  • Status codes — 401 missing or invalid key, 403 insufficient scope or API not enabled, 404 resource not in your workspace, 429 rate limited.
  • Idempotency — event ingest dedupes on an id you provide (source_event_id or externalId), so retries are safe.
Server-key API access (gt_live_ keys) is enabled per workspace. If you get 403 API v1 is not enabled for this workspace, enable it in your workspace settings or contact support.

Quickstart

Make your first request and send your first event.

Authentication

API key types, scopes, and error codes.
Last modified on July 6, 2026