---
title: Search objects
description: Ranks the objects or passages of one target against a text.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Search objects

`POST /v1/workspaces/{workspaceId}/search`

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.

## Authentication

Send `Authorization: Bearer <GRAPHON_API_KEY>`. Read the key from the
GRAPHON_API_KEY environment variable. Never print it.

## Path parameters

- `workspaceId` (string) — The workspace id.

## Request body

- `target` (string) — What to query: a bucket id (bkt…) of this workspace with indexing enabled, or a dataset id (dst…) from List datasets.
- `query` (string) — The text to search for. It must contain text. At most 32,000 characters.
- `mode` (string (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.
- `resultType` (string (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.
- `limit` (integer (optional)) — Results on one page, 1 to 100. Defaults to 10.
- `cursor` (string (optional)) — nextCursor from the previous page. Send it with the same body. It works for 40 minutes.
- `keys` (string[] (optional)) — Use only these object keys. At most 50. With keyPrefix, an object must match both. Defaults to every object of the bucket.
- `keyPrefix` (string (optional)) — Use only the objects whose key begins with this text, for example videos/2026/. Defaults to every object of the bucket.
- `filter` (object (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.

## Example request

```bash
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}'
```

## CLI

```bash
graphon search support-tickets "connection pool" --limit 20
```

## Example 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": []
}
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.