> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gaintrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first GainTrace API call in a couple of minutes.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Read your companies">
    Call the companies endpoint with your key as a Bearer token.

    <CodeGroup>
      ```bash cURL theme={"system"}
      curl "https://app.gaintrace.com/api/v1/companies?limit=5" \
        -H "Authorization: Bearer gt_live_your_key_here"
      ```

      ```javascript Node theme={"system"}
      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");
      ```

      ```python Python theme={"system"}
      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")
      ```
    </CodeGroup>

    ```json Response theme={"system"}
    {
      "data": [
        { "id": "…", "name": "Acme Corp", "healthScore": 82, "healthStatus": "Healthy", "arr": 4800000, "plan": "Scale" }
      ],
      "meta": { "limit": 5, "offset": 0, "count": 1 }
    }
    ```
  </Step>

  <Step title="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).

    <CodeGroup>
      ```bash cURL theme={"system"}
      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" }
            }
          ]
        }'
      ```

      ```javascript Node theme={"system"}
      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" },
            },
          ],
        }),
      });
      ```
    </CodeGroup>

    ```json Response theme={"system"}
    { "data": { "inserted": 1, "duplicates": 0, "linked": 1, "errors": 0 } }
    ```
  </Step>
</Steps>

<Tip>
  Ingest is idempotent on the id you provide (`source_event_id` for `/events`,
  `externalId` for `/metric-events`), so retries never double-count.
</Tip>

## Next steps

<Columns cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Key types, scopes, and error codes.
  </Card>

  <Card title="API reference" icon="code">
    Open the **API reference** tab for every endpoint, request, and response.
  </Card>
</Columns>