Content Analysis API
Keyword mention search
Web citations of a keyword from news, Hacker News and Reddit with deterministic per-mention sentiment (in-adapter lexicon, no AI), Monocrawl category labels and per-source provenance. Fans out to 3 upstreams; coverage is partial and every response names what it could not consult.
Endpoint
GET/v1/content_analysis/searchlive · proven3 creditsParameters
Query parameters
| Name | Required | Description | Example |
|---|---|---|---|
keyword | yes | Phrase to find mentions of | kubernetes |
page_type | no | all, news, forum, social or discussion — maps onto our source roster; review/blog/ecommerce classes are rejected with an explanation rather than silently served from the wrong sources | all |
search_mode | no | as_is (default) or one_per_domain (keep the first mention per publisher) | as_is |
limit | no | Mentions per page after merging (max 100) | 25 |
cursor | no | Offset into the merged result set, from a previous response | 25 |
order_by | no | published_at:desc|asc, sentiment:desc|asc, source or relevance | published_at:desc |
depth | no | Items fetched PER SOURCE before merging (max 100) | 25 |
positive_connotation_threshold | no | Score in (0,1] at or above which a mention is labelled positive | 0.25 |
sentiments_connotation_threshold | no | Score magnitude at or below which a mention is labelled negative | 0.25 |
filters | no | field:op:value segments joined by ; — see /v1/content_analysis/filters | source:in:hackernews,reddit;sentiment:eq:negative |
dry_run | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. | 1 |
Examples
Make the request
curl
curl "https://www.monocrawl.com/v1/content_analysis/search?keyword=kubernetes" \ -H "x-api-key: mn_your_key_here"
TypeScript
typescript
const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const res = await fetch(
"https://www.monocrawl.com/v1/content_analysis/search?keyword=kubernetes",
{ headers: { "x-api-key": key } },
);
const body = await res.json();
if (!body.success) {
// one error shape for every endpoint — see /docs/errors
throw new Error(`${body.error.type}: ${body.error.message}`);
}
console.log(body.data, "credits left:", body.credits_remaining);Python
python
import os
import requests
res = requests.get(
"https://www.monocrawl.com/v1/content_analysis/search?keyword=kubernetes",
headers={"x-api-key": os.environ["MONOCRAWL_API_KEY"]},
timeout=60,
)
body = res.json()
if not body["success"]:
# one error shape for every endpoint — see /docs/errors
raise RuntimeError(f"{body['error']['type']}: {body['error']['message']}")
print(body["data"], "credits left:", body["credits_remaining"])Response
Response fields and example
This example is illustrative, not a captured live response. Variable-cost operations may settle a charge different from the list price below. A successful response puts the platform payload in data and reports the exact credits used, remaining balance, request id and cache status beside it.
200 · application/json
{
"success": true,
"platform": "content_analysis",
"endpoint": "/v1/content_analysis/search",
"data": {
"_warnings": [
"example"
],
"count": 0,
"cursor": null,
"dropped": 0,
"duplicates_removed": 0,
"filters_applied": [],
"gathered": 0,
"items": [
{
"author": "example",
"categories": [
"example"
],
"engagement": {
"comments": 0,
"score": 0
},
"matched_terms": [
{}
],
"primary_category": "example",
"published_at": "2026-09-01T12:00:00Z",
"publisher": "example",
"raw_sentiment_score": 0,
"sentiment": {
"label": "example",
"score": 0
},
"source": "example",
"text_source": "example",
"title": "example",
"url": "https://example.com/example"
}
],
"keyword": "example",
"order_by": "example",
"search_mode": "example",
"sentiment_method": {
"ai_used": false,
"kind": "example",
"known_limits": [
"example"
],
"lexicon": {
"diminishers": 0,
"intensifiers": 0,
"negative_terms": 0,
"negators": 0,
"positive_terms": 0,
"total_terms": 0
},
"modifiers": {
"diminisher": "example",
"intensifier": "example",
"matching": "example",
"negation": "example"
},
"scoring": "example",
"thresholds": {
"negative": 0,
"positive": 0
}
},
"sources": [
{
"endpoint": "example",
"error": "example",
"kept": 0,
"ok": false,
"returned": 0,
"source": "example",
"status": 0
}
],
"sources_unavailable": [
{
"reason": "example",
"source": "example"
}
],
"total_matched": 0
},
"credits_used": 3,
"credits_remaining": 99,
"request_id": "req_…",
"cached": false
}The example is illustrative and shows a documented subset of data. The fields below are optional across supported sources; nullable fields can also be absent. Preserve unknown values and accept additional fields.
Schema basis: observed response shapes, not an exhaustive field specification. See schema coverage and validation limits.
Download the data JSON Schema. Validate response.data, not the whole envelope. A valid shape does not establish that every field or source record was returned.
| Field inside data | Type | Meaning |
|---|---|---|
_warnings | array | null | Optional warnings supplied by this operation. Null means unknown. |
count | number | null | Number of records in this response, not lifetime or total matches. |
cursor | string | null | Opaque next-page token; pass it back unchanged. Null does not prove complete history. |
dropped | number | null | Optional dropped supplied by this operation. Null means unknown. |
duplicates_removed | number | null | Optional duplicates removed supplied by this operation. Null means unknown. |
filters_applied | array | null | Source array was empty in the reviewed captures; item fields remain unspecified. |
gathered | number | null | Optional gathered supplied by this operation. Null means unknown. |
items | array | null | Returned records. Source coverage and completeness vary. |
items[].author | string | null | Public author information supplied with this record. |
items[].categories | array | null | Optional categories supplied by this operation. Null means unknown. |
items[].engagement | object | null | Optional engagement supplied by this operation. Null means unknown. |
items[].engagement.comments | number | null | Optional comments supplied by this operation. Null means unknown. |
items[].engagement.score | number | null | Optional score supplied by this operation. Null means unknown. |
items[].matched_terms | array | null | Optional matched terms supplied by this operation. Null means unknown. |
items[].primary_category | string | null | Optional primary category supplied by this operation. Null means unknown. |
items[].published_at | string | null | Source publication time when available. |
items[].publisher | string | null | Optional publisher supplied by this operation. Null means unknown. |
items[].raw_sentiment_score | number | null | Optional raw sentiment score supplied by this operation. Null means unknown. |
items[].sentiment | object | null | Optional sentiment supplied by this operation. Null means unknown. |
items[].sentiment.label | string | null | Optional label supplied by this operation. Null means unknown. |
items[].sentiment.score | number | null | Optional score supplied by this operation. Null means unknown. |
items[].source | string | null | Optional source supplied by this operation. Null means unknown. |
items[].text_source | string | null | Optional text source supplied by this operation. Null means unknown. |
items[].title | string | null | Source title when supplied. |
items[].url | string | null | Original source URL when supplied. |
keyword | string | null | Optional keyword supplied by this operation. Null means unknown. |
order_by | string | null | Optional order by supplied by this operation. Null means unknown. |
search_mode | string | null | Optional search mode supplied by this operation. Null means unknown. |
sentiment_method | object | null | Optional sentiment method supplied by this operation. Null means unknown. |
sentiment_method.ai_used | boolean | null | Optional ai used supplied by this operation. Null means unknown. |
sentiment_method.kind | string | null | Optional kind supplied by this operation. Null means unknown. |
sentiment_method.known_limits | array | null | Optional known limits supplied by this operation. Null means unknown. |
sentiment_method.lexicon | object | null | Optional lexicon supplied by this operation. Null means unknown. |
sentiment_method.lexicon.diminishers | number | null | Optional diminishers supplied by this operation. Null means unknown. |
sentiment_method.lexicon.intensifiers | number | null | Optional intensifiers supplied by this operation. Null means unknown. |
sentiment_method.lexicon.negative_terms | number | null | Optional negative terms supplied by this operation. Null means unknown. |
sentiment_method.lexicon.negators | number | null | Optional negators supplied by this operation. Null means unknown. |
sentiment_method.lexicon.positive_terms | number | null | Optional positive terms supplied by this operation. Null means unknown. |
sentiment_method.lexicon.total_terms | number | null | Optional total terms supplied by this operation. Null means unknown. |
sentiment_method.modifiers | object | null | Optional modifiers supplied by this operation. Null means unknown. |
sentiment_method.modifiers.diminisher | string | null | Optional diminisher supplied by this operation. Null means unknown. |
sentiment_method.modifiers.intensifier | string | null | Optional intensifier supplied by this operation. Null means unknown. |
sentiment_method.modifiers.matching | string | null | Optional matching supplied by this operation. Null means unknown. |
sentiment_method.modifiers.negation | string | null | Optional negation supplied by this operation. Null means unknown. |
sentiment_method.scoring | string | null | Optional scoring supplied by this operation. Null means unknown. |
sentiment_method.thresholds | object | null | Optional thresholds supplied by this operation. Null means unknown. |
sentiment_method.thresholds.negative | number | null | Optional negative supplied by this operation. Null means unknown. |
sentiment_method.thresholds.positive | number | null | Optional positive supplied by this operation. Null means unknown. |
sources | array | null | Optional sources supplied by this operation. Null means unknown. |
sources[].endpoint | string | null | Optional endpoint supplied by this operation. Null means unknown. |
sources[].error | string | null | Optional error supplied by this operation. Null means unknown. |
sources[].kept | number | null | Optional kept supplied by this operation. Null means unknown. |
sources[].ok | boolean | null | Optional ok supplied by this operation. Null means unknown. |
sources[].returned | number | null | Optional returned supplied by this operation. Null means unknown. |
sources[].source | string | null | Optional source supplied by this operation. Null means unknown. |
sources[].status | number | null | Optional status supplied by this operation. Null means unknown. |
sources_unavailable | array | null | Optional sources unavailable supplied by this operation. Null means unknown. |
sources_unavailable[].reason | string | null | Optional reason supplied by this operation. Null means unknown. |
sources_unavailable[].source | string | null | Optional source supplied by this operation. Null means unknown. |
total_matched | number | null | Optional total matched supplied by this operation. Null means unknown. |
Optional fields reviewed from preserved successful responses. Additive fields and source variations remain allowed; validate the fields your workflow requires.
The example is invented and illustrates types only; zero and empty values are not claims about a real result.
Failures use the typed error envelope. A confirmed uncharged or refunded failure reports zero; a pending reconciliation can report an unknown charge. Read credits_used and error.details.billing_status, and keep request_id for recovery. Response contract · Error reference