> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seedops.co/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> SeedOps CLI browser login is the default for agents. Use --limit 1–50 to retrieve only needed signals. Read /agent-setup/prompt.md for setup. Never request credentials in a prompt.

# Semantic search

> Find published company activities by meaning with the CLI and API.

Semantic search is opt-in. Existing keyword searches and the Activities page keep their current behavior.
Use CLI 0.3.0 or newer:

```bash theme={null}
npm install --global https://www.seedops.co/downloads/seedops-cli-0.3.0.tgz
seedops search --semantic "companies expanding their engineering teams" --limit 5 --pretty
```

Browser login remains the default. Add `--api` to use your separate API-key allowance.
`--pretty` changes JSON formatting only.

## Filters and ranking

Combine `--semantic` with company, location, industry, headcount, date, hiring, funding and advanced group filters.
Add `--q` when the activity title must also contain specific literal keywords. Use the country value returned by search results (for example `US`) rather than substituting a display label.

```bash theme={null}
seedops search --semantic "companies opening new international offices" \
  --country US --days 30 --limit 5

seedops search --filters '{"semantic":"software teams expanding infrastructure capacity","industries":["Software Development"],"limit":5}'
```

The query is embedded with the same Gemini `gemini-embedding-001`, `CLUSTERING`, 768-dimensional configuration used for the published corpus. Raw vectors are not returned.

Search retrieves up to **1,000 approximate nearest published embedded signals**, then applies structured and keyword filters. Filters do not search outside this bounded pool. Narrow filters may therefore return fewer results even when other matching records exist elsewhere. Signals without embeddings are not included.

Items are ordered by cosine distance ascending (equivalently, `similarity` descending), with descending signal ID as the tie-breaker. `similarity` ranges from -1 to 1. It is a ranking score, not a probability, confidence threshold or guarantee of business fit. Review the signal evidence and dates before making a recommendation. No results are synthesized.

The response retains `items` and `nextCursor`, with semantic metadata under `search`:

```json theme={null}
{
  "items": [{"id":"123","title":"An activity title","similarity":0.78}],
  "nextCursor":"...",
  "search": {
    "mode":"semantic",
    "model":"gemini-embedding-001",
    "ranking":"cosine_similarity",
    "candidateLimit":1000,
    "asOf":"2026-10-20T12:00:00.000Z",
    "cursorExpiresAt":"2026-10-20T13:00:00.000Z"
  }
}
```

## Limits and pagination

* Semantic query: 3–1,000 characters.
* `--limit`: 1–50, default 50.
* Only returned records count toward usage. A limit of five can return fewer than five.
* Continue with `--cursor`, repeating the same semantic query, filters and limit. Pages are never fetched automatically.
* Cursors expire after one hour. They bind the query, filters, limit, last rank and first-page publication cutoff.
* `--page`, `--ids` and `--count` / `countOnly=true` are not supported in semantic mode. Keyword searches retain these options.

```bash theme={null}
seedops search --semantic "companies expanding their engineering teams" --limit 5 --cursor '<nextCursor>'
```

Approximate nearest-neighbor retrieval and corpus corrections can change candidate coverage between calls. The publication cutoff excludes later publications, but this is not a frozen database snapshot or an exhaustive export.

## API

```bash theme={null}
curl --get 'https://app.seedops.co/api/v1/signals' \
  --header "Authorization: Bearer $SEEDOPS_API_KEY" \
  --data-urlencode 'semantic=companies expanding their engineering teams' \
  --data-urlencode 'limit=5'
```

Browser-login CLI uses `/api/cli/v1/signals` with its existing CLI session. Do not send browser cookies to API-key endpoints.

## Billing, privacy and failures

Semantic and keyword modes use the same record allowances: browser-login CLI uses CLI records; API keys use separate API records. One returned signal consumes one record. Empty results, failed requests and idempotent replays consume no data records. There is no separate SeedOps semantic-record surcharge.

The semantic query text is sent to Google's existing Gemini embedding service. Keyword-only searches do not use that service. A bounded in-memory cache may reuse an identical query embedding for one hour; this reuse is best-effort across Worker instances. Authentication tokens, API keys and full company profiles are not sent for query embedding.

Missing embedding configuration or provider/database failures return `503` with an actionable error. Semantic mode never silently falls back to keywords. Retry with the same `--idempotency-key` to avoid charging twice for a completed request. Do not repeatedly retry `429`; respect `Retry-After`. Use `seedops usage` to check your allowance for free.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.