Streaming search API

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.

Access token
OAuth token

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"

curl --header "Accept: text/event-stream" \
     --header "Authorization: Bearer YOUR_OAUTH_TOKEN" \
     --get \
     --url "https://sourcegraph.example.com/.api/search/stream" \
     --data-urlencode "q=YOUR_QUERY" \
     --data-urlencode "v=V3"

Query parameters

Parameter	Required	Description
`q`	Yes	A Sourcegraph search query. See search query syntax.
`v`	No	Query syntax version. Use `V3` (default and recommended).
`t`	No	Pattern type: `keyword`, `standard`, or `regexp`. Only applied if `q` doesn’t already contain `patternType:`. Default: `standard`.
`display`	No	Maximum number of matches to return. The backend continues searching and computing statistics after this limit. Default: no limit.
`cm`	No	Enable chunk matches (`true`/`false`). Provides richer match context. Default: `false`.
`max-line-len`	No	Truncate lines in `ChunkMatch` results to this length. Default: no limit.
`cl`	No	Number 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

Event	Description
`matches`	Search results. Each match can be of type `content`, `path`, `commit`, `diff`, `symbol`, or `repo`.
`progress`	Aggregated statistics: match count, repository count, duration, and skipped reasons.
`filters`	Suggested filters to narrow the search further.
`alert`	Info, warning, or error messages from the search backend.
`done`	Always 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

Sourcegraph CLI (src-cli): src search -stream "your query" — available at sourcegraph/src-cli
TypeScript/JavaScript: a community-maintained client for Node.js, browsers, and Deno is available at ziv/source-graph-stream-client

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.

Administration

Integrations & API

Endpoint

Authentication

Query parameters

Event stream format

Event types

Example

Use cases

Exhaustive search over all repositories

CI integration

Client libraries

​Endpoint

​Authentication

​Query parameters

​Event stream format

​Event types

​Example

​Use cases

​Exhaustive search over all repositories

​CI integration

​Client libraries

Endpoint

Authentication

Query parameters

Event stream format

Event types

Example

Use cases

Exhaustive search over all repositories

CI integration

Client libraries