Skip to main content
The Sourcegraph GraphQL API provides broad access to data stored and computed by your Sourcegraph instance. It is primarily intended for diagnostics and simple tooling.
The GraphQL API is an internal interface without formal backwards-compatibility guarantees. It may change across Sourcegraph releases. For external integrations, use the REST API introduced in Sourcegraph 7.0. If your use case is not yet covered by the REST API, contact [email protected].
For code search integrations, use the streaming search API instead. It is purpose-built for consuming search results and is the same API used by the Sourcegraph UI.

​
Endpoint

POST https://sourcegraph.example.com/.api/graphql
Send requests as JSON with a query field (the GraphQL query string) and an optional variables field.

​
Authentication

Generate a personal access token under Settings > Access tokens, then pass it in the Authorization header:
curl -H "Authorization: token YOUR_TOKEN" \
  -d '{"query": "query { currentUser { username } }"}' \
  https://sourcegraph.example.com/.api/graphql
A successful authentication check returns: 
{"data": {"currentUser": {"username": "your-username"}}}

​
Example queries

​
Verify authentication

curl -H "Authorization: token YOUR_TOKEN" \
  -d '{"query": "query { currentUser { username } }"}' \
  https://sourcegraph.example.com/.api/graphql

​
Search for code

curl -H "Authorization: token YOUR_TOKEN" \
  -d '{
    "query": "query($q: String!) { search(query: $q) { results { matchCount } } }",
    "variables": {"q": "Router lang:go"}
  }' \
  https://sourcegraph.example.com/.api/graphql

​
Look up a repository

curl -H "Authorization: token YOUR_TOKEN" \
  -d '{
    "query": "query { repository(name: \"github.com/sourcegraph/sourcegraph\") { name description defaultBranch { name } } }"
  }' \
  https://sourcegraph.example.com/.api/graphql

​
Read a file

curl -H "Authorization: token YOUR_TOKEN" \
  -d '{
    "query": "query { repository(name: \"github.com/sourcegraph/sourcegraph\") { commit(rev: \"HEAD\") { file(path: \"README.md\") { content } } } }"
  }' \
  https://sourcegraph.example.com/.api/graphql

​
API console

Sourcegraph ships with a built-in API console where you can write queries and browse the schema interactively.
  • Navigate to Settings > Debug console in your Sourcegraph instance, or visit https://sourcegraph.example.com/debug/console directly.
  • Click Docs on the right side of the console to browse the schema documentation.
  • You can also use the Sourcegraph.com debug console to test against the latest API version.

​
Sourcegraph CLI

The src-cli provides a command-line interface to the GraphQL API. It reads your access token and instance URL from a config file or environment variables, handles JSON escaping, and lets you pipe multi-line queries easily. 
# Get a curl equivalent for any query
src api -get-curl -query 'query { currentUser { username } }'

​
Query cost limits

To protect system stability, Sourcegraph enforces limits on GraphQL query complexity. These defaults can be adjusted in site configuration under rateLimits.
SettingDefaultDescription
graphQLMaxDepth30Maximum nesting depth of objects in a query
graphQLMaxFieldCount500,000Maximum number of fields in a response
graphQLMaxAliases500Maximum number of aliases in a single query
graphqlMaxDuplicateFieldCount500Maximum duplicate fields in a query
graphqlMaxUniqueFieldCount500Maximum unique fields in a query
Use pagination where available to stay within the graphQLMaxFieldCount limit when working with large data sets.

Build docs developers (and LLMs) love

Get started for freeTalk to us