Search objects

Ranks the objects or passages of one target against a text. The target is a bucket with indexing enabled, or a dataset from List datasets. Each result is an object and the spans in it that matched: pages of a document, characters of a text file, or seconds of a video or a recording. A span holds no text: read it with Read spans. Read the whole object of a bucket from the storage API with its key and versionId. Scope the search with keys, keyPrefix, or a metadata filter. Requires the viewer role. An empty bucket returns no results and the warning index_empty. Nothing is stored.

POST/v1/workspaces/{workspaceId}/search

Authentication

Send your Graphon API key with every request. The value is the whole API key that Graphon showed when you created it. See Authentication.

Authorization: Bearer <GRAPHON_API_KEY>

curl \
  --url "https://api.beta.graphon.ai/v1/workspaces/wspq7ws2np5l8z4/search" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"target":"bktA1b2C3d4E5","query":"checkout connection pool exhausted","mode":"hybrid","resultType":"object","limit":10}'

Request

Loading your session…

Response

JSON

{
  "results": [
    {
      "key": "incidents/2026-10-03-checkout.pdf",
      "versionId": "ver_3f9c2a7d1e4b4c8a9f0d6b2e5a1c7d3f",
      "contentType": "application/pdf",
      "rank": 1,
      "score": 0.83,
      "spans": [
        {
          "key": "incidents/2026-10-03-checkout.pdf",
          "versionId": "ver_3f9c2a7d1e4b4c8a9f0d6b2e5a1c7d3f",
          "unit": "chars",
          "start": 18240,
          "end": 19310,
          "pages": {
            "start": 4,
            "end": 5
          }
        }
      ]
    }
  ],
  "nextCursor": "eyJ2IjoxLCJnIjoiZ2VuXzAxSkE3UTNWOEsifQ",
  "execution": {
    "mode": "hybrid"
  },
  "indexGeneration": "gen_01JA7Q3V8K2M4N6P8R0T2W4Y6Z",
  "timingMs": {
    "retrieval": 34,
    "total": 47
  },
  "warnings": []
}

Path parameters

workspaceIdstring

The workspace id.

Request body

targetstring

What to query: a bucket id (bkt…) of this workspace with indexing enabled, or a dataset id (dst…) from List datasets.

querystring

The text to search for. It must contain text. At most 32,000 characters.

modestring (optional)

hybrid: Use it for most searches. It matches exact words and meaning together. About a second. keyword: Use it for exact words, such as an ID, a code, or an error message. The quickest mode. Defaults to hybrid. One of: hybrid, keyword.

resultTypestring (optional)

The kind of result. object: one result per object, with up to 3 spans. passage: one span per result, so an object can appear more than once. Both have the same shape. Defaults to object. One of: object, passage.

limitinteger (optional)

Results on one page, 1 to 100. Defaults to 10.

cursorstring (optional)

nextCursor from the previous page. Send it with the same body. It works for 40 minutes.

keysstring[] (optional)

Use only these object keys. At most 50. With keyPrefix, an object must match both. Defaults to every object of the bucket.

keyPrefixstring (optional)

Use only the objects whose key begins with this text, for example videos/2026/. Defaults to every object of the bucket.

filterobject (optional)

Use only the objects whose metadata matches. A clause is { field, op, value } on a metadata field that the bucket lists. text takes every operator. number and time take eq, neq, gt, gte, lt, and lte. bool takes eq and neq. A value is text, a number or a decimal string, an RFC 3339 time, or true or false; in takes an array of 1 to 100 values. and, or, and not combine clauses, at most 4 levels deep and 32 clauses in all. neq and not keep objects that have no value for the field. With keys or keyPrefix, an object must match all of them. A field that is still indexing after a change fails with metadata_field_indexing.

Was this page helpful?

View as Markdown