# Sourcegraph Analytics API

The Sourcegraph Analytics API is an API that provides programmatic access to your Sourcegraph Analytics data, including usage metrics, user activity, and performance data.

## Access tokens

For Sourcegraph Analytics, you can generate an access token for programmatic access. Tokens are long-lived with an optional expiry and have the same permissions to access instance data as the user who created them.

To get started, visit the [Sourcegraph Analytics access tokens management page](http://analytics.sourcegraph.com/access-tokens). From here, you can create, view, and revoke access tokens for your Sourcegraph Account.

## API reference

To authenticate to the API, follow the instructions for [token creation](#token-creation).

Export your access token as an environment variable:

```sh
export ACCESS_TOKEN="<ACCESS_TOKEN>"
```

### CSV export

To generate a CSV export of the data for a specific instance, run the following commands:

```sh
export INSTANCE_URL="<INSTANCE URL>" # e.g. example.sourcegraphcloud.com

curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL" \
 -H "Authorization: Bearer $ACCESS_TOKEN"
```

Optional granularity values can be specified. If not specified, the default is `by_user_day_client_language`.

-   `by_user`,
-   `by_user_month`,
-   `by_user_day`,
-   `by_user_day_client_language`

```sh
export INSTANCE_URL="<INSTANCE_URL>" # e.g. example.sourcegraphcloud.com
export GRANULARITY="<GRANULARITY>"

curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL&granularity=$GRANULARITY" \
 -H "Authorization: Bearer $ACCESS_TOKEN"
```

Optional `startDate` and `endDate` values (formatted as `YYYY-MM-DD`) can be specified. Both parameters are optional. If neither is specified, the default is all time. If only one is specified, then only the start or end date filter will be applied.

Example:

```sh
export INSTANCE_URL="<INSTANCE_URL>" # e.g. example.sourcegraphcloud.com
export START_DATE="2025-01-01"
export END_DATE="2025-12-31"

curl -X GET "https://analytics.sourcegraph.com/api/reports/by-user-client-date?instanceURL=$INSTANCE_URL&startDate=$START_DATE&endDate=$END_DATE" \
 -H "Authorization: Bearer $ACCESS_TOKEN"
```

### User registry export

The user registry endpoint returns the current user registry snapshot for a Sourcegraph instance as CSV. The required `instanceURL` must identify an instance that your access token has permission to access.

The export contains the following columns:

- `Instance user ID`: The numeric ID assigned to the user by the Sourcegraph instance.
- `Service Account`: Whether the user is a service account (`true` or `false`).
- `Site Admin`: Whether the user is a site administrator (`true` or `false`).

To download the user registry:

```sh
export INSTANCE_URL="<INSTANCE_URL>" # e.g. example.sourcegraphcloud.com

curl --fail-with-body --get \
 "https://analytics.sourcegraph.com/api/reports/user-registry" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 --data-urlencode "instanceURL=$INSTANCE_URL" \
 --output user_registry.csv
```

### Credit buckets

The credits API endpoint provides access to credit bucket allocations and consumption for your instance. To retrieve this data, run the following commands:

```sh
export INSTANCE_URL="<INSTANCE_URL>" # e.g. example.sourcegraphcloud.com

curl -X GET "https://analytics.sourcegraph.com/api/credits?instanceURL=$INSTANCE_URL" \
 -H "Authorization: Bearer $ACCESS_TOKEN"
```

Optional `startDate` and `endDate` values (formatted as `YYYY-MM-DD`) can be specified to filter buckets by their active period. Both parameters are optional. If neither is specified, all buckets are returned.

Example:

```sh
export INSTANCE_URL="<INSTANCE_URL>" # e.g. example.sourcegraphcloud.com
export START_DATE="2026-05-01"
export END_DATE="2026-12-31"

curl -X GET "https://analytics.sourcegraph.com/api/credits?instanceURL=$INSTANCE_URL&startDate=$START_DATE&endDate=$END_DATE" \
 -H "Authorization: Bearer $ACCESS_TOKEN"
```