Skip to main content
1

Get an API key

In GainTrace, go to Settings → API Keys, create a key, and grant the scopes you need (for example read:companies, write:events). Copy the key — it’s shown once.
2

Read your companies

Call the companies endpoint with your key as a Bearer token.
curl "https://app.gaintrace.com/api/v1/companies?limit=5" \
  -H "Authorization: Bearer gt_live_your_key_here"
Response
{
  "data": [
    { "id": "…", "name": "Acme Corp", "healthScore": 82, "healthStatus": "Healthy", "arr": 4800000, "plan": "Scale" }
  ],
  "meta": { "limit": 5, "offset": 0, "count": 1 }
}
3

Send a product event

Push a usage event so it flows into health, signals, and activation. Identify the account with account_id (its external id or UUID).
curl -X POST "https://app.gaintrace.com/api/v1/events" \
  -H "Authorization: Bearer gt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "report_exported",
        "account_id": "acme-corp",
        "user_id": "u_123",
        "timestamp": "2026-07-05T12:00:00Z",
        "source_event_id": "evt_abc123",
        "properties": { "format": "pdf" }
      }
    ]
  }'
Response
{ "data": { "inserted": 1, "duplicates": 0, "linked": 1, "errors": 0 } }
Ingest is idempotent on the id you provide (source_event_id for /events, externalId for /metric-events), so retries never double-count.

​
Next steps

Authentication

Key types, scopes, and error codes.

API reference

Open the API reference tab for every endpoint, request, and response.
Last modified on July 6, 2026