Get search status and retained results

Retrieve the status and saved results of a search started with POST /v1/searches. Use this endpoint to follow a search that is still running or to retrieve its results again while they are retained.

This reads the existing search without starting new work. Start a new search to change the query, targets, or result page.

Selector catalogue

Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.

Selector	Data	Default
`results`	Matching items, their text, relevance scores, source locations, and coverage information.	Yes
`results.highlights`	Highlight locations within result titles and summaries. Also includes `results`.	No
`results.*`	Results and highlights together.	No
`sources`	Source status, applied filters, coverage, and suggested documentation sites.	No
`progress`	Search request details, readiness counts, and available or suggested versions and refs.	No

GET

searches

{search_ref}

Get search status and retained results

curl --request GET \
  --url https://api.githits.dev/v1/searches/{search_ref} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.githits.dev/v1/searches/{search_ref}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.githits.dev/v1/searches/{search_ref}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.githits.dev/v1/searches/{search_ref}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.githits.dev/v1/searches/{search_ref}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "completed": false,
  "expires_at": null,
  "query_warnings": [],
  "result": null,
  "search_ref": "opaque-search-ref",
  "selected_fields": [
    "results"
  ],
  "status": "pending",
  "targets": [
    {
      "coverage": null,
      "freshness": null,
      "indexing_ref": null,
      "requested": "site:example.org/docs",
      "resolved_requested": "site:example.org/docs",
      "served": null,
      "target_resolution": null
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version

string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent

string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID

string

Optional caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]{1,64}$

Path Parameters

search_ref

string

required

Opaque effective-user-owned reference; encode as one path segment, decoded exactly once without trimming.

Minimum string length: 1

Query Parameters

fields

string

default:results

Comma-separated results/results.highlights/results.*/sources/progress; default results, 2048 decoded bytes. No arbitrary leaf masks.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

Maximum string length: 2048

wait_timeout_ms

integer

default:20000

Time to wait for an updated search observation, in milliseconds. Default 20000; zero returns immediately. When only progress is selected, a positive wait can continue until the search is terminal or the wait expires.

Required range: 0 <= x <= 60000

Response

Source-qualified active, interim or retained terminal observation

One canonical source observation; a reference does not imply active work.

completed

boolean

required

Source POST completion flag; GET is true exactly for completed status. Other terminal statuses remain false.

expires_at

string | null

required

Source expiration timestamp, not a gateway retention guarantee or exact 410 boundary.

query_warnings

string[]

required

Parser warnings from the result or inline progress, never inferred from query text.

result

null | object

required

Latest complete page; null when results is unselected or no page is available. Inspect selected_fields.

Show child attributes

search_ref

string | null

required

Effective-user-owned opaque reference; null for an immediate unreferenced result.

selected_fields

enum<string>[]

required

Canonical expanded selected groups in stable order; disambiguates unselected result:null.

Atomic evidence groups, independent of the transport protocol.

Available options:

results,

results.highlights,

sources,

progress

status

null | enum<string>

required

Explicit source session state, null when the initial operation supplies none.

Available options:

pending,

indexing,

searching,

completed,

deferred,

timeout,

failed

targets

object[] | null

required

Concise readiness/provenance supplied by inline progress; null when absent.

Show child attributes

progress

null | object

Omitted when unselected; null when selected without inline progress.

Show child attributes

sources

null | object

Omitted when unselected; null when selected without a source snapshot.

Show child attributes

⌘I

Get search status and retained results

curl --request GET \
  --url https://api.githits.dev/v1/searches/{search_ref} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.githits.dev/v1/searches/{search_ref}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.githits.dev/v1/searches/{search_ref}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.githits.dev/v1/searches/{search_ref}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.githits.dev/v1/searches/{search_ref}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "completed": false,
  "expires_at": null,
  "query_warnings": [],
  "result": null,
  "search_ref": "opaque-search-ref",
  "selected_fields": [
    "results"
  ],
  "status": "pending",
  "targets": [
    {
      "coverage": null,
      "freshness": null,
      "indexing_ref": null,
      "requested": "site:example.org/docs",
      "resolved_requested": "site:example.org/docs",
      "served": null,
      "target_resolution": null
    }
  ]
}

Get started

v1 reference

Get search status and retained results

Selector catalogue

Authorizations

Headers

Path Parameters

Query Parameters

Response