API reference

Keyword Mention Trends API

Mention volume and sentiment for a keyword bucketed by day, week or month across the sources we can reach. Bucket heights are bounded by each source's per-query cap, so the series is a shape, not a census — the response says so explicitly.

Read as Markdown Use with an AI agent

Endpoint

GET/v1/content_analysis/phrase-trendslive · proven5 credits

Try in Playground

Parameters

Query parameters

Useful optional inputs

date_to — Bound the end of the documented date window.
Source acquisition and local filtering retain their documented costs.
depth — Bound collection to the documented number of records or source pages.
Depth semantics vary by endpoint and may affect the quote.
dry_run — Read a free estimate before fetching sources or scheduling paid work.
Zero credits; cache status and availability are snapshots rather than guarantees.

Name	Required	Description	Example
`keyword`	yes	Phrase to trend	`kubernetes`
`date_from`	yes	ISO-8601 start of the window	`2026-08-01`
`date_to`	no	ISO-8601 end of the window (default now)	`2026-08-31`
`date_group`	no	day (default), week or month; max 400 buckets Accepted values: day, week, month. Case, spaces, hyphens and underscores are interchangeable.	`day`
`page_type`	no	all, news, forum, social or discussion Accepted values: all, news, forum, social, discussion. Case, spaces, hyphens and underscores are interchangeable.	`all`
`internal_list_limit`	no	Length of the embedded top-terms list (max 50)	`10`
`depth`	no	Items fetched PER SOURCE before bucketing (max 100)	`100`
`filters`	no	field:op:value segments joined by ; — see /v1/content_analysis/filters	`source:eq:hackernews`
`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. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.	`1`

Examples

Make the request

curl

curl "https://www.monocrawl.com/v1/content_analysis/phrase-trends?keyword=kubernetes&date_from=2026-08-01" \
  -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/phrase-trends?keyword=kubernetes&date_from=2026-08-01",
  { 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/phrase-trends?keyword=kubernetes&date_from=2026-08-01",
    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/phrase-trends",
  "data": {
    "_warnings": [
      "example"
    ],
    "bucket_count": 0,
    "buckets": [
      {
        "bucket_end": "example",
        "bucket_start": "example",
        "by_source": {
          "google_news": 0,
          "hackernews": 0,
          "reddit": 0
        },
        "mentions": 0,
        "sentiment": {
          "mean_score": 0,
          "negative": 0,
          "neutral": 0,
          "positive": 0
        }
      }
    ],
    "date_from": "2026-09-01T12:00:00Z",
    "date_group": "2026-09-01T12:00:00Z",
    "date_to": "2026-09-01T12:00:00Z",
    "excluded": {
      "out_of_window_mentions": 0,
      "undated_mentions": 0
    },
    "filters_applied": [],
    "keyword": "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"
      }
    ],
    "top_terms": [
      {
        "mentions": 0,
        "occurrences": 0,
        "term": "example"
      }
    ],
    "totals": {
      "buckets_with_mentions": 0,
      "duplicates_removed": 0,
      "gathered_before_filters": 0,
      "mentions": 0,
      "peak_bucket": {
        "bucket_start": "example",
        "mentions": 0
      },
      "sentiment": {
        "max_score": 0,
        "mean_score": 0,
        "median_score": 0,
        "min_score": 0,
        "negative": 0,
        "neutral": 0,
        "positive": 0,
        "total": 0
      }
    }
  },
  "credits_used": 5,
  "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.
`bucket_count`	`number \| null`	Optional bucket count supplied by this operation. Null means unknown.
`buckets`	`array \| null`	Optional buckets supplied by this operation. Null means unknown.
`buckets[].bucket_end`	`string \| null`	Optional bucket end supplied by this operation. Null means unknown.
`buckets[].bucket_start`	`string \| null`	Optional bucket start supplied by this operation. Null means unknown.
`buckets[].by_source`	`object \| null`	Optional by source supplied by this operation. Null means unknown.
`buckets[].by_source.google_news`	`number \| null`	Optional google news supplied by this operation. Null means unknown.
`buckets[].by_source.hackernews`	`number \| null`	Optional hackernews supplied by this operation. Null means unknown.
`buckets[].by_source.reddit`	`number \| null`	Optional reddit supplied by this operation. Null means unknown.
`buckets[].mentions`	`number \| null`	Optional mentions supplied by this operation. Null means unknown.
`buckets[].sentiment`	`object \| null`	Optional sentiment supplied by this operation. Null means unknown.
`buckets[].sentiment.mean_score`	`number \| null`	Optional mean score supplied by this operation. Null means unknown.
`buckets[].sentiment.negative`	`number \| null`	Optional negative supplied by this operation. Null means unknown.
`buckets[].sentiment.neutral`	`number \| null`	Optional neutral supplied by this operation. Null means unknown.
`buckets[].sentiment.positive`	`number \| null`	Optional positive supplied by this operation. Null means unknown.
`date_from`	`string \| null`	Optional date from supplied by this operation. Null means unknown.
`date_group`	`string \| null`	Optional date group supplied by this operation. Null means unknown.
`date_to`	`string \| null`	Optional date to supplied by this operation. Null means unknown.
`excluded`	`object \| null`	Optional excluded supplied by this operation. Null means unknown.
`excluded.out_of_window_mentions`	`number \| null`	Optional out of window mentions supplied by this operation. Null means unknown.
`excluded.undated_mentions`	`number \| null`	Optional undated mentions supplied by this operation. Null means unknown.
`filters_applied`	`array \| null`	Source array was empty in the reviewed captures; item fields remain unspecified.
`keyword`	`string \| null`	Optional keyword 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.
`top_terms`	`array \| null`	Optional top terms supplied by this operation. Null means unknown.
`top_terms[].mentions`	`number \| null`	Optional mentions supplied by this operation. Null means unknown.
`top_terms[].occurrences`	`number \| null`	Optional occurrences supplied by this operation. Null means unknown.
`top_terms[].term`	`string \| null`	Optional term supplied by this operation. Null means unknown.
`totals`	`object \| null`	Optional totals supplied by this operation. Null means unknown.
`totals.buckets_with_mentions`	`number \| null`	Optional buckets with mentions supplied by this operation. Null means unknown.
`totals.duplicates_removed`	`number \| null`	Optional duplicates removed supplied by this operation. Null means unknown.
`totals.gathered_before_filters`	`number \| null`	Optional gathered before filters supplied by this operation. Null means unknown.
`totals.mentions`	`number \| null`	Optional mentions supplied by this operation. Null means unknown.
`totals.peak_bucket`	`object \| null`	Optional peak bucket supplied by this operation. Null means unknown.
`totals.peak_bucket.bucket_start`	`string \| null`	Optional bucket start supplied by this operation. Null means unknown.
`totals.peak_bucket.mentions`	`number \| null`	Optional mentions supplied by this operation. Null means unknown.
`totals.sentiment`	`object \| null`	Optional sentiment supplied by this operation. Null means unknown.
`totals.sentiment.max_score`	`number \| null`	Optional max score supplied by this operation. Null means unknown.
`totals.sentiment.mean_score`	`number \| null`	Optional mean score supplied by this operation. Null means unknown.
`totals.sentiment.median_score`	`number \| null`	Optional median score supplied by this operation. Null means unknown.
`totals.sentiment.min_score`	`number \| null`	Optional min score supplied by this operation. Null means unknown.
`totals.sentiment.negative`	`number \| null`	Optional negative supplied by this operation. Null means unknown.
`totals.sentiment.neutral`	`number \| null`	Optional neutral supplied by this operation. Null means unknown.
`totals.sentiment.positive`	`number \| null`	Optional positive supplied by this operation. Null means unknown.
`totals.sentiment.total`	`number \| null`	Source-reported total; null is 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

Keyword Mention Trends API

Query parameters

Make the request

Response fields and example

Useful next calls

First call in under a minute