Semantic search

GET /api/v1/entries?query=... finds news entries whose meaning is closest to a natural-language query. The entries list endpoint treats ?query= as semantic by default: instead of matching exact words, it embeds your query into a vector and ranks entries by how close they sit in that vector space, so it surfaces relevant articles even when they use different wording.

Semantic vs keyword search

?query= on the entries list is semantic by default, with two deterministic exceptions that route to an exact/keyword lookup:

• a bare UUID → entry id lookup,
• a source: / publisher: / topic: / asset: prefix → the keyword mini-DSL.

Everything else is treated as a natural-language query and matched by meaning.

	?query= (keyword exceptions)	?query= (semantic, default)
Triggered by	a UUID or a source:/publisher:/topic:/asset: prefix	any other text
Matches on	Keywords / exact	Meaning (vector similarity)
Finds synonyms & paraphrases	No	Yes
Ranked by	Recency / sort order	Cosine similarity
Credit cost	1	2
Pagination	Cursor-based (after/before)	None — single ranked page

Use a prefix or UUID when you know the exact ticker, id, or source. Use a natural-language query when you’re describing a topic — for example, "central bank tightening cycle" will surface entries about rate hikes, hawkish Fed minutes, and balance-sheet runoff even if those exact words never appear.

Note

In semantic mode sortBy, the after/before cursors and the structured filters (topicSlug, assetKey, …) are ignored — vector ranking has no stable cursor. Only limit (capped at 50) and maxAgeHours apply.

Request

GET /api/v1/entries?query=<natural-language text>

Parameters

Parameter	Required	Description
query	No	Natural-language query to embed and match semantically (semantic by default).
limit	No	Max results. Capped at 50 and by your tier (see below).
maxAgeHours	No	Only match entries created within this many hours (e.g. 24 for last day).

Examples

curl

curl -s -G "https://api.quantconomy.com/api/v1/entries" \
  --data-urlencode "query=Federal Reserve interest rate decision" \
  --data-urlencode "limit=10" \
  --data-urlencode "maxAgeHours=48" \
  -H "Authorization: Bearer mtk_your_key_here"

JavaScript

const url = new URL('https://api.quantconomy.com/api/v1/entries');
url.searchParams.set('query', 'Federal Reserve interest rate decision');
url.searchParams.set('limit', '10');
url.searchParams.set('maxAgeHours', '48');

const res = await fetch(url, {
  headers: { Authorization: 'Bearer mtk_your_key_here' },
});
const { data, meta } = await res.json();

Python

import requests

res = requests.get(
    "https://api.quantconomy.com/api/v1/entries",
    params={
        "query": "Federal Reserve interest rate decision",
        "limit": 10,
        "maxAgeHours": 48,
    },
    headers={"Authorization": "Bearer mtk_your_key_here"},
)
data = res.json()["data"]

Other queries that work well:

• AI chip export restrictions
• central bank tightening cycle
• oil supply disruption in the Middle East
• regional bank deposit outflows

Response

Semantic results use the same entry shape as the list endpoint, plus a similarity score and matchType. The meta reports source: "qdrant" and a single ranked page (hasMore: false, no cursors).

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Fed Holds Rates Steady, Signals Caution on Future Cuts",
      "url": "https://reuters.com/markets/us/fed-holds-rates-2024",
      "urlDomain": "reuters.com",
      "publishedAt": "2024-01-15T19:00:00.000Z",
      "createdAt": "2024-01-15T19:05:00.000Z",
      "similarity": 0.87,
      "matchType": "embedding"
    }
  ],
  "meta": {
    "totalCount": 10,
    "count": 10,
    "limit": 10,
    "hasMore": false,
    "hasPrev": false,
    "nextCursor": null,
    "prevCursor": null,
    "sort": "similarity:desc",
    "query": "Federal Reserve interest rate decision",
    "source": "qdrant"
  }
}

Result fields

Field	Description
id	Entry UUID. Fetch the full article via GET /api/v1/entries/{id}.
title	Article title.
url	Original article URL.
urlDomain	Domain of the article URL (e.g. reuters.com).
publishedAt	Original publication date.
createdAt	When the entry was added to the system.
similarity	Cosine similarity score, 0–1. Higher is a closer match.
matchType	embedding on semantically-ranked rows.

meta fields

Field	Description
count	Number of entries returned.
limit	The effective limit that was applied.
query	The query string that was embedded.
source	Search engine that served the result (qdrant for semantic, keyword otherwise).

Note

Results are filtered to a minimum similarity, so a vague query may return fewer than limit entries — only genuinely close matches are included.

Credit cost

A semantic ?query= request costs 2 credits (multiplied by your plan’s credit multiplier). The same endpoint with no ?query= — or a UUID / source:-style prefix that routes to keyword lookup — costs 1 credit per page.

The vector backend that powers ranking can occasionally be unavailable; in that case the endpoint returns 503 with a SERVICE_UNAVAILABLE error code — retry shortly. See Plans & credits for credit balances and Errors for status codes.

Authentication & limits

This endpoint requires an API key — the free demo key (mtk_demo) works.

• Demo key callers are capped at 3 results and spend 2 credits per semantic request from the shared hourly demo budget.
• Your own key gives up to your tier’s result limit, with a hard ceiling of 50 results, and spends 2 credits per semantic request.

Use your own key to raise your result cap — see Authentication.

Related

• Pagination & filtering — the cursor-paginated entries list and keyword/prefix lookups.
• Plans & credits — credit costs and balances.
• Entries API reference