Natural Language Query Usage

The Natural Language endpoints allow search queries to be generated or refined using a natural language prompt.

These endpoints return a query and a preview of up to 25 matching mentions.

Available operations

Operation	Starting point	Saves changes?
POST /query/generate	Natural language prompt	No
POST /query/refine/{topicId}	Existing saved topic and Natural language prompt	No
POST /query/refine	Query supplied in the request and Natural language prompt	No

Natural Language Query Behaviour

Generate

• The prompt describes the desired search coverage.
• The prompt may specify search terms and supported filters such as media type, publication date, language, sentiment, and location.
• The generated query may omit fields that cannot be inferred from the prompt.
• The generated query can be submitted to a search endpoint or used as the starting point for refinement.
• Generating a query does not create or modify a saved topic.

Refine

• Refinement starts with an existing query, either from a saved topic identified by topicId or from the query supplied in the request.
• The prompt describes the changes to make to that query.
• Refinement can modify supported query fields, including the expert query, media types, publication date, language, sentiment, and location.
• Prompts should describe the intended change rather than restating the entire query.
• Fields not affected by the requested change are retained.
• Refinement does not modify the saved topic or persist the resulting query.

When to use generate vs refine

Use POST /query/generate when you want to create a query from scratch using a natural language description.

Use POST /query/refine/{topicId} when you want to modify the query associated with an existing saved topic without changing the saved topic itself.

Use POST /query/refine when you already have a query and want to modify it without referencing a saved topic.

Supported Query Fields

Natural language generation and refinement can work with the following query fields:

• expertQuery — search areas (HEADLINE, LEAD, BODY) and Expert Search expression.
• mediaTypes — supported media types such as ONLINE_NEWS, TV, PODCAST, and REDDIT.
• publicationDate — relative date range or an absolute date range.
  • Some relative date ranges examples are TODAY, YESTERDAY, LAST_7_DAYS, and LAST_30_DAYS.
• language — language codes with INCLUDE or EXCLUDE.
• caseSensitive — whether keyword matching is case-sensitive.
• sentiments — POSITIVE, NEUTRAL, NEGATIVE, or UNSET.
• location — geographic filters for continents, countries, provinces, cities, and counties, with INCLUDE or EXCLUDE.

These fields are represented in the generated or refined query returned by the endpoint.

Generate a query

Use POST /query/generate to create a new search query from a natural language prompt.

{
  "prompt": "Tesla coverage across Europe from the last 7 days"
}

The response contains the generated query and a preview of matching mentions:

{
  "query": {
    "expertQuery": {
      "areas": ["HEADLINE", "BODY"],
      "search": "Tesla"
    },
    "publicationDate": {
      "relative": "LAST_7_DAYS"
    },
    "location": {
      "continents": {
        "codes": [9],
        "inclusionType": "INCLUDE"
      }
    }
  },
  "preview": []
}

The generated query can be used with the appropriate search endpoint or further refined using the Natural Language refinement endpoints.

Generating a query does not create or modify a saved topic.

Refine a saved topic query

Use POST /query/refine/{topicId} to refine the query associated with an existing saved topic.

The topicId identifies the existing query used as the starting point. The request contains a natural language prompt describing the desired changes.

Request:

{
  "prompt": "Tesla coverage from the last 30 days"
}

Response:

{
  "query": {
    "expertQuery": {
      "areas": ["HEADLINE", "BODY"],
      "search": "Tesla"
    },
    "publicationDate": {
      "relative": "LAST_30_DAYS"
    },
    "location": {
      "continents": {
        "codes": [9],
        "inclusionType": "INCLUDE"
      }
    }
  },
  "preview": []
}

The existing saved topic is used as the starting point, and the response contains the refined query and a preview of matching mentions.

A refinement prompt can request changes to any supported query field, including the expert query, media types, publication date, language, sentiment, or location.

The saved topic is not modified. The refined query is returned only as part of the response.

Refine a query directly

Use POST /query/refine when the query to be refined is supplied directly in the request.

Request:

{
  "query": {
    "expertQuery": {
      "areas": ["HEADLINE", "BODY"],
      "search": "Tesla"
    },
    "publicationDate": {
      "relative": "LAST_7_DAYS"
    }
  },
  "prompt": "Change Tesla to Toyota and include podcasts"
}

Response:

{
  "query": {
    "expertQuery": {
      "areas": ["HEADLINE", "BODY"],
      "search": "Toyota"
    },
    "mediaTypes": ["PODCASTS"],
    "publicationDate": {
      "relative": "LAST_7_DAYS"
    }
  },
  "preview": []
}

The response contains the refined query and a preview of matching mentions.

This endpoint does not save the refined query.

Writing effective prompts

Natural language prompts produce better results when they clearly describe the intended search or change.

For query generation:

• Include the main subject, such as Tesla, "Calgary Flames", or electric vehicles.
• Specify a time period when relevant, such as yesterday, last 7 days, or January 2026.
• Specify media types when relevant, such as news articles, podcasts, or Reddit posts.
• Include location, language, or sentiment requirements when relevant.
• Use specific names or phrases when they are important to the search.

For query refinement:

• Describe the desired change relative to the existing query.
• Be explicit about what should be added, removed, or changed.
• For example: Exclude Germany, Change Tesla to SpaceX, or Change the date range to the last 30 days.

The generated or refined expertQuery.search value follows the same Expert Search syntax described in Search Usage.