Stream events and coverage
A successful search returns server-sent events (SSE), not a JSON array. Read the response incrementally as UTF-8 text. Blank lines delimit frames; each frame has an event name and JSON data.
The examples below are illustrative. They describe the v1 wire format, not a particular live search.
Event lifecycle
Section titled “Event lifecycle”start → hit / progress → done ↘ errorThere can be zero hits and zero progress events. done and error are terminal. If the connection ends without either, mark the search incomplete. Network chunk boundaries are not event boundaries: buffer until a complete blank-line-delimited frame is available.
The first event describes source, matching mode, coverage, and limits.
event: startdata: {"api_version":1,"source":"github","query_mode":"literal","coverage":{"live_commit_history_included":false,"partial":true,"historical_snapshots":true,"current_head_complete":false,"deleted_or_superseded_content_may_be_present":true},"limits":{"max_hits":100,"max_runtime_seconds":45,"max_frame_bytes":65536,"max_output_bytes":1048576}}| Field | Type | Meaning |
|---|---|---|
api_version | integer | 1. |
source | string | github. |
query_mode | string | literal. |
coverage | object | Corpus-coverage facts supplied by this search. |
limits | object | Maximum hits, runtime, frame size, and total output. |
The coverage values shown are examples; use the values received for your request.
Each event is one file match. Its payload is the hit itself, without a hit wrapper.
event: hitdata: {"source":"github","kind":"file","id":"example-hit-id","repository":"example/project","path":"config/example.txt","commit":"0123456789abcdef0123456789abcdef01234567","extension":"txt","bytes":120,"snippet":"service_host=example.com","match":"example.com"}| Field | Type | Meaning |
|---|---|---|
source | string | github. |
kind | string | file. |
id | string | Result identifier, up to 256 characters. Treat as opaque. |
repository | string | owner/repository, up to 201 characters. |
path | string | File path, up to 16,384 characters. |
commit | string | 40-character hexadecimal commit identifier. |
extension | string | Extension label, up to 64 characters; may be empty. |
bytes | integer | Indexed file size in bytes, nonnegative. |
snippet | string | Preview text, up to 600 characters; not the full file. |
match | string | Matched text, up to 256 characters. |
Results do not include a relevance score, a line number, full-file contents, or a GitHub URL field. You may construct a source link from the repository, commit, and properly encoded path. A historical file may no longer exist on the current branch.
progress
Section titled “progress”event: progressdata: {"elapsed_ms":1000}elapsed_ms is an integer elapsed-time indicator. It is not a percentage, a hit-count forecast, or proof that all sources are reachable. Progress intervals are not guaranteed.
event: donedata: {"status":"limited","count":100,"limited":true,"partial":true,"coverage":{"live_commit_history_included":false,"partial":true,"historical_snapshots":true,"current_head_complete":false,"deleted_or_superseded_content_may_be_present":true}}| Field | Type | Meaning |
|---|---|---|
status | string | complete, limited, or paused. |
count | integer | Number of emitted hit events. |
limited | boolean | Whether the upstream result set reached a result bound. |
partial | boolean | True when paused, limited, or the corpus coverage is partial. |
coverage | object | Coverage facts for this run. |
complete means this bounded execution finished. It does not mean every GitHub file was searched. limited means a bound restricted results. paused means partial matches were retained when execution stopped early. A paused result can have limited: false.
event: errordata: {"code":"search_unavailable","partial":true,"count":2,"coverage":{"live_commit_history_included":false,"partial":true,"historical_snapshots":true,"current_head_complete":false,"deleted_or_superseded_content_may_be_present":true}}This terminal event reports a stream failure after the HTTP response opened. Retain existing hits and mark the run incomplete. count is the number of hits already emitted; partial is true. There is no resumable cursor or automatic replay protocol.
Coverage fields
Section titled “Coverage fields”All five fields are booleans. Store their actual values rather than replacing them with assumptions.
| Field | Interpretation |
|---|---|
live_commit_history_included | Whether the search includes live commit history. |
partial | Whether the searched corpus has partial coverage. |
historical_snapshots | Whether historical snapshots are represented. |
current_head_complete | Whether coverage represents complete current-head content. |
deleted_or_superseded_content_may_be_present | Whether results can include content deleted or replaced later. |
A zero-hit result means no matches were returned within that query’s covered corpus and execution bounds. It is not an assurance that an organization has no exposure.
A reliable consumer
Section titled “A reliable consumer”- Check HTTP status and content type before parsing SSE.
- Decode UTF-8 incrementally and assemble complete frames.
- Parse the
dataJSON according to the event name. - Retain
startmetadata before processing hits. - Record every hit as received; avoid logging sensitive previews unnecessarily.
- Record exactly one terminal outcome, including coverage and completeness.
- Treat EOF without a terminal event as interrupted.
Native browser EventSource is not suitable for this POST endpoint with bearer authentication. Use a streaming HTTP client on your server. Do not automatically reconnect as if this were a replayable feed: each new POST starts a new search.