---
title: "Semantic search over events (Pro+)"
method: GET
path: "/v1/search"
tags: ["search"]
---

# Semantic search over events (Pro+)

`GET /v1/search`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/v1/search`
- Auth: API key in header `X-Api-Key`

Natural-language query embedded and ranked by cosine similarity against published events — not a keyword/text match. Each result is a normal event object plus `relevance_score` (0-1). Requires Pro tier or above; free-tier keys get 403 with an upgrade_url.

## Query parameters

- `q` string, required: Natural-language search query
- `limit` integer

## Response `200`

Successful Response

- SearchListResponse
  - `data` SearchResult[], required
    - `event_id` string, required
    - `schema_version` string, required
    - `taxonomy_version` string, required
    - `primary_category` string, required
    - `subcategory` string, required
    - `categories` string[], required
    - `type_confidence` 0.9 | 0.6 | 0.3, required
    - `headline` string, required
    - `summary` string, required
    - `occurred_at` string, date-time, nullable
    - `reported_at` string, date-time, required
    - `orgs` string[], required
    - `models` string[], required
    - `source_url` string, required
    - `article_count` integer, required
    - `people` string[], nullable
    - `regions` string[], nullable
    - `confirmation_status` 'confirmed' | 'unconfirmed' | 'speculative' | 'unclear'
    - `confirmation_confidence` number, nullable
    - `source_tier` 'PRIMARY' | 'TIER1_PRESS' | 'SECONDARY' | 'SOCIAL'
    - `source_credibility` number, nullable
    - `sentiment` 'positive' | 'negative' | 'neutral' | 'mixed'
    - `impact_score` number, nullable
    - `tags` string[], nullable
    - `related_event_ids` string[], nullable
    - `correction_history` object[], nullable
    - `details` object, nullable
    - `article_cluster` object[], nullable
    - `relevance_score` number, required: Cosine similarity to the query, 0-1, higher is more relevant.
  - `pagination` Pagination, required
    - `next_cursor` string, nullable
    - `has_more` boolean, required
    - `count` integer, required
  - `meta` Meta, required
    - `request_id` string, required
    - `taxonomy_version` string, required
    - `tier` 'free' | 'pro' | 'enterprise', required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/scoopkit/apis/scoopkit-api.md) · [All operations](https://skmtc.dev/scoopkit/apis/scoopkit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scoopkit/apis/scoopkit-api/revisions/18068781261d?raw)