# 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"
```