---
title: search_catalog
description: Ranked full-text catalog search with job expansion, stats and access states, up to 200 rows a page.
---

<WorksIn />

Ranked full-text search over every endpoint, with job expansion: a query matching a job's title
or alias ("verify an email") returns every endpoint of that job across providers, and an
unmatched sentence falls back to looser word overlap. Free and read-only. Use it over
[`search`](/mcp-tools/search) when you want more than 5 results, a whole category, or the
30-day stats and access state on each row.

## Inputs

| Argument | Type | Required | Default | Limits | Meaning |
| --- | --- | --- | --- | --- | --- |
| `query` | string | No | - | max 500 chars | Plain-English description or job phrase. Optional with a filter. |
| `limit` | integer | No | - | 1-200 | Rows per page. |
| `offset` | integer | No | 0 | 0+ | Row offset; `nextOffset` in the answer is `null` at the end. |
| `detail` | string | No | - | `title` \| `full` | `title` drops summary, stats, job and matchedBy for a cheap first pass. |
| `prefer` | string | No | `"balanced"` | `cheapest` \| `reliable` \| `fastest` \| `balanced` | Orders providers inside a job. |
| `filters.category` | string | No | - | - | Restrict to a category; browse it with no `query`. |
| `filters.platform` | string | No | - | - | Restrict to a platform. |
| `filters.provider` | string | No | - | - | Restrict to a provider. |
| `filters.capability` | string | No | - | - | A job id, e.g. from `expandedCapabilities`. |
| `filters.keyless` | boolean | No | - | - | Only endpoints that need no key at all. |
| `filters.verified` | boolean | No | - | - | Only endpoints verified against a saved provider answer. |
| `filters.mock` | boolean | No | - | - | Include fixture/demo endpoints (ranked last otherwise). |
| `filters.maxPriceMicros` | number | No | - | 0+ | Drop rows priced above this, in micros of a dollar. |
| `filters.hidden` | boolean | No | - | - | Include hidden endpoints. |
| `filters.includeUnavailable` | boolean | No | - | - | Include endpoints with no route to run right now. |

Each row carries `category`, `job` (id, title), `matchedBy` (`text` \| `capability` \| `tokens`),
`mock`, `verified`, `keyless`, `runnableNow`, `stats` (30-day calls, successRate, p50Ms,
sampleSize; `null` without evidence), and `access`: `runs_now`, `needs_your_account` or
`coming_soon`. `capability` is the job id, `sourceCapability` the raw registered slug,
`credential` whose key a run uses. `expandedCapabilities` lists matched job ids; pass one as
`filters.capability` to narrow to it. Rows come back under `items`.

## Example call

```json
{
  "query": "linkup",
  "limit": 5
}
```

## Example answer

Abridged: full rows also carry `mock`, `verified`, `keyless`, `runnableNow` and `stats`.

```json
{
  "query": "linkup",
  "total": 13,
  "offset": 0,
  "nextOffset": 10,
  "expandedCapabilities": [],
  "items": [
    {
      "endpointId": "linkup-search",
      "provider": "Linkup",
      "name": "Linkup API / /search",
      "capability": "search.get",
      "category": "search",
      "estimatedPrice": 0.005,
      "priceBasis": "perCall",
      "access": "runs_now"
    },
    {
      "endpointId": "linkup-fetch",
      "provider": "Linkup",
      "name": "Linkup API / /fetch",
      "capability": "fetch.get",
      "category": "fetch",
      "estimatedPrice": 0.001,
      "priceBasis": "perCall",
      "access": "runs_now"
    }
  ]
}
```

## Errors

Free and read-only; no `runs.execute` needed. A bad `filters` key returns [`validation_error`](/errors/rest-errors#validation_error)
naming it, for example `Unrecognized key: "colour" at filters`. An unsupplied job returns an
empty `items` array with `unsuppliedJobs` and `warnings` naming it, not an error. When
`filters.maxPriceMicros` removes every match, `items` is empty and `priceHint` names the
cheapest row it dropped.

## REST and CLI

- REST: [`GET /v1/catalog/search`](/reference/catalog/get-v1-catalog-search) (REST returns rows under `endpoints`, this tool under `items`)
- CLI: `looot search "<query>"`

<Related />