Skip to content

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.

start → hit / progress → done
↘ error

There 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: start
data: {"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}}
FieldTypeMeaning
api_versioninteger1.
sourcestringgithub.
query_modestringliteral.
coverageobjectCorpus-coverage facts supplied by this search.
limitsobjectMaximum 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: hit
data: {"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"}
FieldTypeMeaning
sourcestringgithub.
kindstringfile.
idstringResult identifier, up to 256 characters. Treat as opaque.
repositorystringowner/repository, up to 201 characters.
pathstringFile path, up to 16,384 characters.
commitstring40-character hexadecimal commit identifier.
extensionstringExtension label, up to 64 characters; may be empty.
bytesintegerIndexed file size in bytes, nonnegative.
snippetstringPreview text, up to 600 characters; not the full file.
matchstringMatched 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.

event: progress
data: {"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: done
data: {"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}}
FieldTypeMeaning
statusstringcomplete, limited, or paused.
countintegerNumber of emitted hit events.
limitedbooleanWhether the upstream result set reached a result bound.
partialbooleanTrue when paused, limited, or the corpus coverage is partial.
coverageobjectCoverage 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: error
data: {"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.

All five fields are booleans. Store their actual values rather than replacing them with assumptions.

FieldInterpretation
live_commit_history_includedWhether the search includes live commit history.
partialWhether the searched corpus has partial coverage.
historical_snapshotsWhether historical snapshots are represented.
current_head_completeWhether coverage represents complete current-head content.
deleted_or_superseded_content_may_be_presentWhether 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.

  1. Check HTTP status and content type before parsing SSE.
  2. Decode UTF-8 incrementally and assemble complete frames.
  3. Parse the data JSON according to the event name.
  4. Retain start metadata before processing hits.
  5. Record every hit as received; avoid logging sensitive previews unnecessarily.
  6. Record exactly one terminal outcome, including coverage and completeness.
  7. 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.