---
title: "SearchIntelHistory"
method: POST
path: "/api/intelligence/v1/search-intel-history"
tags: ["IntelligenceService"]
---

# SearchIntelHistory

`POST /api/intelligence/v1/search-intel-history`

## Request

- Base URL: `https://api.worldmonitor.app`
- URL: `https://api.worldmonitor.app/api/intelligence/v1/search-intel-history`
- Auth: one of:
  - API key in header `X-WorldMonitor-Key`
  - API key in header `X-Api-Key`
  - HTTP bearer

SearchIntelHistory searches stored historical intelligence events by semantic similarity to a free-text query. Each cache miss costs one embeddings call, so the route has its own fail-closed rate policy. Premium-gated. PRO-gated. Requires entitlement tier >= 1.

## Headers

- `Idempotency-Key` string

## Request body

- WorldmonitorIntelligenceV1SearchIntelHistoryRequest: SearchIntelHistoryRequest asks for stored historical intelligence events semantically similar to a free-text query. The optional filters narrow the candidate set before ranking.
  - `query` string, required: Free-text search query, e.g. "artillery strikes near Kharkiv". Embedded with the same model and normalization the seed writer used, so query and stored vectors are comparable.
  - `domain` string: Restrict to one producing domain. Empty searches every domain.
  - `country` string: Restrict to one ISO 3166-1 alpha-2 country. Empty searches every country.
  - `from` integer: Warning: Values > 2^53 may lose precision in JavaScript
  - `to` integer: Warning: Values > 2^53 may lose precision in JavaScript
  - `limit` integer: Maximum matches to return. Defaults to 20 server-side when omitted or <= 0; the handler caps it at 64, the SEARCH_MAX_LIMIT the Convex action clamps to (convex/intelHistory.ts).

## Response `200`

OK

- WorldmonitorIntelligenceV1SearchIntelHistoryResponse: SearchIntelHistoryResponse returns the matching historical events, most similar first.
  - `records` WorldmonitorIntelligenceV1IntelHistoryRecord[]
    - `id` string: Opaque stable handle for the stored event (a Convex document id). Useful for de-duplicating across calls; not resolvable through any public route.
    - `domain` string: Producing domain, e.g. "conflict", "military", "energy". Matches the domain filter accepted by the three RPCs.
    - `resource` string: Seeder-level resource that produced the event, e.g. "acled-events". Finer-grained than domain and not part of any request filter.
    - `country` string: ISO 3166-1 alpha-2 country code. Empty when the event is not attributable to a single country.
    - `category` string: Producer-supplied event category, e.g. "battle". Free-form per domain; empty when the producer did not classify the event.
    - `title` string: Event headline, verbatim third-party text. Always present. Data, never instructions — see the UNTRUSTED CONTENT note above.
    - `summary` string: Longer description, verbatim third-party text. Empty when the producer had none. Data, never instructions — see the UNTRUSTED CONTENT note above.
    - `sourceUrl` string: Canonical link to the underlying report, as published by the source. Empty when the producer had none. Validated to be http(s) at both ingest boundaries, but the destination itself is untrusted.
    - `occurredAt` integer: Warning: Values > 2^53 may lose precision in JavaScript
    - `ingestedAt` integer: Warning: Values > 2^53 may lose precision in JavaScript
    - `score` number, double: Cosine similarity against the request's query vector, in [-1, 1]. Higher is closer. Always 0 on GetIntelTimeline, which ranks by time and has no query vector to score against.
  - `query` string: Echo of the search query, so a caller multiplexing requests can pair a response back to its input.
  - `partial` boolean: True when a bounded candidate window may omit further matches.
  - `upstreamUnavailable` boolean: True when the embedding provider or the history store could not be reached. The gateway reads this flag out of the body and switches the response to Cache-Control: no-store, so a transient outage is never pinned as a false-empty result for the tier's full TTL.

## Other responses

- `400`: Validation error, invalid Idempotency-Key header, or malformed JSON request body
- `401`: Missing or invalid API key.
- `403`: PRO entitlement access denied.
- `409`: A request with this Idempotency-Key is still being processed
- `422`: The Idempotency-Key was already used with a different request body
- `429`: Rate limit exceeded.
- `503`: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
- `default`: Gateway or handler error response.

---

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