---
title: "Smart content search powered by Signal AI's trained concepts"
method: POST
path: "/search"
tags: ["Content Search"]
---

# Smart content search powered by Signal AI's trained concepts

`POST /search`

With our smart content search, you can find documents of interest to you from Signal AI's live indexed content (the world's largest dataset of real-time, global news and regulatory information). You are able to search over the last 15 months of indexed content.

A search response will contain a page of `documents` metadata matching the search query.


### Search query criteria
Construct a query to find documents of your interest, by specifying some matching criteria. In particular, you can use the `where`, and the `exclude` clauses in the request body (see below).
The `where` clause defines criteria that the documents returned should match, whereas the `exclude` clause is the opposite and defines criteria that documents must not match (i.e. it filters out documents that match those criteria)

The criteria that can be used for matching documents in the query include:
* the entities mentioned in the document (up to 200 per query)
* the topics that the document relates to (up to 100 per query)
* the publication sources or countries, regions or subregions of publication (up to 500 sources per query)
* the IPTC categories that the document relates to
* the publication date & time
* the language of the document
* the media type of the document (online or print)
* the document story ID (up to 200 per query)

Note that for the `exclude` clause, only the the first three criteria can be used (entities, topics and sources)

### Documents metadata returned
The metadata returned for each document matching the query includes:
  * unique document ID
  * story ID
  * document title
  * native language document title (for non-english content)
  * Signal url (for online content only)
  * publication source and location (country, subregion & region)
  * publication date & time
  * the media type of the document (e.g. online)
  * the language of the document
  * the full list of topics that the document pertains to
  * the full list of IPTC categories that the document pertains to
  * the full list of entities mentioned in the document, with the content position, saliency and associated sentiment label for each mention

### Sorting
Documents can be sorted by:
  * `published-at` - publication date (default)
  * `score` - relevance score

The direction of sorting can be specified as:
  * `desc` - descending (default)
  * `asc` - ascending

### Pagination limitations

⚠️   **Pagination is not supported when sorting results by relevance score**

You can only get one page of documents (up to the maximum page size of 500), and the response will not include a `next-cursor` field.

### Story deduplication
Signal AI identifies syndicated articles pertaining to the same story and assigns them the same `story-id`. This can be useful for the purpose of deduplicating articles if you are interested in unique stories only. Because the publication of syndicated articles on the same story can span several hours or sometimes even days, there is no guarantee that all articles on the same story will be listed contiguously in the API response.

### Keyword limitations
In order to use the inclusion keywords, you must include **at least** one of `entities`, `source` or `topics` in the `where` clause of the request.

There is a **50 word** limit on keywords across inclusion and exclusion. A keyword can be made up of sevaral words, i.e. the keyword `Big Tech` would count as **2 words**.

## Request body

- DocumentSearchQuery — unresolved $ref

## Response `200`

Returns a list of documents matching the search query

- DocumentSearchResponse
  - `stats` SearchStats, required
    - `total` integer, required — Approximate total number of documents matching this search
  - `documents` Document[], required
    - `story-id` string, uuid
    - `signal-url` string
    - `regulatory-document` 'alert' | 'announcement' | 'bill' | 'circular' | 'consultation paper' | 'decision' | 'enforcement' | 'general' | 'guidance' | 'hearing' | 'interview' | 'judgement' | 'legislation' | 'letter' | 'opinion' | 'parliamentary commentary' | 'policy paper' | 'press release' | 'publication' | 'resolution' | 'sanctions' | 'speech' | 'statement' | 'tender' | 'transcript' | 'transparency' | 'warning' | 'other' — <span class="beta-tag"></span> Regulatory document categorisation
    - `entities` EntityWithMentions[], required
      - `id` string, uuid, required
      - `type` 'person' | 'organisation' | 'location' | 'substance' | 'disease' | 'product' | 'regulation', required
      - `name` string, required
      - `sentiment` 'positive' | 'negative' | 'neutral', required
      - `salient` boolean — Indicates if this entity is truly central to the content of the document
      - `salience-rank` integer — Indicates how close this entity is to the topic of discussion in the article, in relation to other entities mentioned. A lower rank means a higher salience.
      - `mentions` Mention[], required — The positions of the entity in the document
        - `position` 'content' | 'summary' | 'title' | 'quote', required
        - `sentiment` 'positive' | 'negative' | 'neutral'
    - `published-at` string, date-time, required
    - `source` Source, required
      - `id` string, uuid, required
      - `name` string, required
      - `country` string
      - `subregion` string
      - `region` string
    - `title` string, required
    - `topics` PartialTopic[], required
      - `id` string, uuid, required
      - `name` string, required
    - `categories` object
      - `iptc-media-topics` Category[]
        - `id` string, uuid, required
        - `name` string, required
    - `language` string
    - `id` string, uuid, required
    - `native-title` string — Document title in its native language (for non english content)
    - `media-type` 'online' | 'print', required
  - `next-cursor` string

---

[API](https://skmtc.net/signal-ai/apis/signal-ai-api.md) · [All operations](https://skmtc.net/signal-ai/apis/signal-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signal-ai/signal-ai-api/revisions/0ab7ff186291/schema)