> ## 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.

# Introduction

> The GainTrace REST API — read your customer data and push usage events and signals.

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](/authentication) 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:

```json theme={"system"}
{
  "data": [],
  "meta": { "limit": 50, "offset": 0, "count": 50 }
}
```

Errors return an `error` string, sometimes with `detail` or `code`:

```json theme={"system"}
{ "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.

<Note>
  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.
</Note>

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first request and send your first event.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key types, scopes, and error codes.
  </Card>
</Columns>