---
title: "Global search"
method: GET
path: "/api/search/global"
tags: ["search", "search"]
---

# Global search

`GET /api/search/global`

## Query parameters

- `q` string — Free-form search query (semantic + lexical). When empty or omitted, the endpoint returns the most-recently-updated items per bucket instead.
- `per_type_limit` integer — Maximum items returned per bucket. The response contains *at most* this many agents, files, and chats — fewer when the bucket has no/few matches.

## Response `200`

Successful Response

- GlobalSearchResponse — Top-N hits bucketed by item type. For a non-empty query this contains hybrid-search results. For an empty query this contains the most-recently-updated items per bucket (cached per-user with a short TTL).
  - `agents` SearchResultItem[]
    - `id` string, required
    - `type` 'library_agent' | 'store_agent' | 'workspace_file' | 'chat_session', required
    - `title` string, required
    - `subtitle` string, nullable
    - `metadata` object
    - `score` number, nullable
    - `updated_at` string, date-time, nullable
  - `files` SearchResultItem[]
    - `id` string, required
    - `type` 'library_agent' | 'store_agent' | 'workspace_file' | 'chat_session', required
    - `title` string, required
    - `subtitle` string, nullable
    - `metadata` object
    - `score` number, nullable
    - `updated_at` string, date-time, nullable
  - `chats` SearchResultItem[]
    - `id` string, required
    - `type` 'library_agent' | 'store_agent' | 'workspace_file' | 'chat_session', required
    - `title` string, required
    - `subtitle` string, nullable
    - `metadata` object
    - `score` number, nullable
    - `updated_at` string, date-time, nullable

## Other responses

- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/significant-gravitas/autogpt-agent-server/versions/382041c7ecb2/schema)