Quickstart - GainTrace

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.

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"

const res = await fetch("https://app.gaintrace.com/api/v1/companies?limit=5", {
  headers: { Authorization: "Bearer gt_live_your_key_here" },
});
const { data, meta } = await res.json();
console.log(meta.count, "companies");

import requests

res = requests.get(
    "https://app.gaintrace.com/api/v1/companies",
    headers={"Authorization": "Bearer gt_live_your_key_here"},
    params={"limit": 5},
)
print(res.json()["meta"]["count"], "companies")

Response

{
  "data": [
    { "id": "…", "name": "Acme Corp", "healthScore": 82, "healthStatus": "Healthy", "arr": 4800000, "plan": "Scale" }
  ],
  "meta": { "limit": 5, "offset": 0, "count": 1 }
}

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" }
      }
    ]
  }'

await fetch("https://app.gaintrace.com/api/v1/events", {
  method: "POST",
  headers: {
    Authorization: "Bearer gt_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      {
        event_name: "report_exported",
        account_id: "acme-corp",
        user_id: "u_123",
        timestamp: new Date().toISOString(),
        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

​Next steps

Authentication

API reference

Next steps