Skip to main content
The Sourcegraph streaming search API delivers search results and metadata as a stream of server-sent events (SSE). The Sourcegraph UI uses this API for all interactive searches. It provides shorter time-to-first-result compared to a single HTTP response and handles exhaustive searches returning large volumes of results without putting pressure on the backend.

​
Endpoint

GET https://sourcegraph.example.com/.api/search/stream

​
Authentication

Pass your access token or OAuth token in the Authorization header. 
curl --header "Accept: text/event-stream" \
     --header "Authorization: token YOUR_TOKEN" \
     --get \
     --url "https://sourcegraph.example.com/.api/search/stream" \
     --data-urlencode "q=YOUR_QUERY" \
     --data-urlencode "v=V3"

​
Query parameters

ParameterRequiredDescription
qYesA Sourcegraph search query. See search query syntax.
vNoQuery syntax version. Use V3 (default and recommended).
tNoPattern type: keyword, standard, or regexp. Only applied if q doesn’t already contain patternType:. Default: standard.
displayNoMaximum number of matches to return. The backend continues searching and computing statistics after this limit. Default: no limit.
cmNoEnable chunk matches (true/false). Provides richer match context. Default: false.
max-line-lenNoTruncate lines in ChunkMatch results to this length. Default: no limit.
clNoNumber of context lines around each match. Requires cm=true. Default: 1.
The display parameter is different from the count: query filter. display limits what is returned to the client, while count: stops the search once that many matches are found.

​
Event stream format

The API responds with a stream of events following the server-sent events format. Each event has an event: line and a data: line. Events are separated by two newline characters (\n\n). The data: field is always JSON. 
event: <event-type>
data: <JSON>

event: <event-type>
data: <JSON>

event: done
data: {}
The stream always ends with a done event.

​
Event types

EventDescription
matchesSearch results. Each match can be of type content, path, commit, diff, symbol, or repo.
progressAggregated statistics: match count, repository count, duration, and skipped reasons.
filtersSuggested filters to narrow the search further.
alertInfo, warning, or error messages from the search backend.
doneAlways the final event. Signals the stream is complete.

​
Example

This example runs a search against Sourcegraph.com (which allows unauthenticated queries for public code): 
curl --header "Accept: text/event-stream" \
     --get \
     --url "https://sourcegraph.com/.api/search/stream" \
     --data-urlencode "q=r:sourcegraph/sourcegraph stream results patternType:keyword count:1" \
     --data-urlencode "v=V3"
Sample response: 
event: filters
data: [{"value":"archived:yes","label":"Include archived repos","count":15,"exhaustive":false,"kind":"utility"}]

event: progress
data: {"done":false,"matchCount":0,"durationMs":206,"skipped":[{"reason":"excluded-archive","title":"15 archived","message":"By default we exclude archived repositories. Include them with `archived:yes` in your query.","severity":"info","suggested":{"title":"include archived","queryExpression":"archived:yes"}}]}

event: matches
data: [{"type":"content","path":"cmd/frontend/graphqlbackend/search_results.go","repositoryID":36809250,"repository":"github.com/sourcegraph/sourcegraph","repoStars":9918,"branches":[""],"commit":"be0cd097f5f20d1444786ed7bb6c34cbad85c676","lineMatches":[{"line":"// Results are the results found by the search. It respects the limits set.","lineNumber":124,"offsetAndLengths":[[3,7]]}],"language":"Go"}]

event: progress
data: {"done":true,"repositoriesCount":1,"matchCount":1,"durationMs":359,"skipped":[]}

event: done
data: {}

​
Use cases

​
Exhaustive search over all repositories

To search all indexed repositories without a result limit, use count:all and remove any repo: filters: 
curl --header "Accept: text/event-stream" \
     --get \
     --url "https://sourcegraph.example.com/.api/search/stream" \
     --data-urlencode "q=TODO count:all" \
     --header "Authorization: token YOUR_TOKEN"
Or using the Sourcegraph CLI: 
src search -stream "TODO count:all"

​
CI integration

The streaming API is well suited for CI checks that need to surface search results quickly — for example, scanning for secrets, deprecated APIs, or banned patterns across pull request diffs. 
# Search for hardcoded credentials in a specific repository
curl --header "Accept: text/event-stream" \
     --header "Authorization: token YOUR_TOKEN" \
     --get \
     --url "https://sourcegraph.example.com/.api/search/stream" \
     --data-urlencode "q=repo:^github\.com/your-org/your-repo$ patternType:regexp (password|secret|api_key)\s*=" \
     --data-urlencode "v=V3"

​
Client libraries

Although the streaming API follows the server-sent events format, Sourcegraph does not guarantee compatibility with generic SSE client libraries. For production use, write a purpose-built wrapper or use the src-cli.

Build docs developers (and LLMs) love

Get started for freeTalk to us