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.
Token management APIs
Token management is currently only available via the Sourcegraph Analytics API. Token management APIs are authenticated via the cas
session cookie.
- Sign in to Sourcegraph Analytics.
- Retrieve your session cookie,
cas
, from your browser's developer tools.
- Export the cookie as an environment variable to use in the following commands:
SHexport CAS_COOKIE="<CAS_COOKIE_VALUE>"
Token creation
Create the token by running the following command:
SHcurl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Content-Type: application/json" \ -H "Cookie: cas=$CAS_COOKIE" \ -d '{}' # Optionally include displayName, expiresAt, or both in the request body. # If expiresAt is not provided, the token will never expire and must be revoked manually. # -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}'
The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. For example:
JSON{ "id": "4cf96e80-d5f3-4af0-a28d-3c70ba97abb4", "displayName": "My Analytics Token", "secret": "sams_at_abcdefghijk", "createdAt": "2025-05-28T12:00:00Z", "expiresAt": "2025-12-31T23:59:59Z" }
Token listing
List the tokens by running the following command:
SHcurl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ -H "Cookie: cas=$CAS_COOKIE"
Each token in the response will include the token ID, creation date, a boolean indicating if the token has expired, and display name and expiration date if provided. For example:
JSON{ "tokens": [ { "id": "5a140b00-3a79-497d-bcfb-c1d2e3d8c747", "displayName": "My Analytics Token", "createdAt": "2025-05-27T12:00:00Z", "expiresAt": "2025-05-27T13:00:00Z", "isExpired": true }, { "id": "eaf8a6f1-1302-43f6-a9ad-f9862d75e959", "createdAt": "2025-05-28T12:30:00Z", "expiresAt": "2025-05-28T13:30:00Z", "isExpired": true }, { "id": "d7df6636-99d0-4266-9f32-a2fb7ccbfcd5", "displayName": "My Analytics Token 2", "createdAt": "2025-05-28T15:00:00Z", "isExpired": false }, { "id": "8ea63000-a164-44ca-8834-bb71e9b788fb", "createdAt": "2025-05-28T15:30:00Z", "isExpired": false } ] }
Token revocation
Revoke a token by running the following commands:
SHexport TOKEN_ID="<TOKEN_ID>" curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKEN_ID \ -H "Cookie: cas=$CAS_COOKIE"
isExpired
is true
.API reference
To authenticate to the API, follow the instructions for token creation.
Export your access token as an environment variable:
SHexport ACCESS_TOKEN="<ACCESS_TOKEN>"
CSV export
To generate a CSV export of the data for a specific instance, run the following commands:
SHexport 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
SHexport 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:
SHexport 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"