---
title: Search objects
description: Ranks the objects or passages of one bucket 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 bucket against a text. Both modes match exact words and meaning together: fast fuses them, and standard then reranks the top results. Each result is an object and the places in it that matched: a page of a document, or a time range in a video or a recording. Read the object itself from the storage API with its key and versionId. Requires the viewer role. The bucket must have indexing enabled. 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

- `bucketId` (string) — The bucket id. The bucket must be in the workspace and have indexing enabled.
- `query` (string) — The text to search for. It must contain text. At most 32,000 characters.
- `mode` (string (optional)) — standard matches exact words and meaning together, then a reranker orders the top 48 results. fast skips the reranker. Defaults to standard. One of: fast, standard.
- `resultUnit` (string (optional)) — object: one result per object, with up to 3 locations. passage: one location per result, so an object can appear more than once. 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.

## 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 '{"bucketId":"bktA1b2C3d4E5","query":"checkout connection pool exhausted","mode":"standard","resultUnit":"object","limit":10}'
```

## Example response

```json
{
  "results": [
    {
      "key": "incidents/2026-10-03-checkout.pdf",
      "versionId": "ver_3f9c2a7d1e4b4c8a9f0d6b2e5a1c7d3f",
      "contentType": "application/pdf",
      "rank": 1,
      "score": 0.83,
      "matchedBy": [
        "keyword",
        "semantic"
      ],
      "locations": [
        {
          "page": 3,
          "snippet": "At 14:02 UTC checkout exhausted its database pool (200 of 200 in use)."
        }
      ]
    }
  ],
  "nextCursor": "eyJ2IjoxLCJnIjoiZ2VuXzAxSkE3UTNWOEsifQ",
  "execution": {
    "mode": "standard",
    "stages": [
      "keyword",
      "semantic",
      "fusion",
      "rerank"
    ]
  },
  "indexGeneration": "gen_01JA7Q3V8K2M4N6P8R0T2W4Y6Z",
  "timingMs": {
    "retrieval": 34,
    "total": 47
  },
  "warnings": []
}
```

## Sitemap

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