API reference

Cross-platform Search API

Cross-platform search as a pipeline: query intent detection, per-source entity resolution (handles are verified before account legs run), fan-out to live sources only, cross-source deduplication, relevance scoring with a floor, and per-source receipts (latency, cost, kept/dropped). A search with nothing relevant returns NO_USEFUL_SIGNAL and charges 0; partial source failures prorate the price. Set estimate=true for a free plan + max-cost preview.

Read as Markdown Use with an AI agent

Endpoint

GET/v1/search/alllive · proven10 credits

Try in Playground

Parameters

Query parameters

Useful optional inputs

timeframe — Choose the source time window relevant to your task.
A narrower window is not a completeness guarantee or a price reduction.
sources — Restrict a multi-source request to the platforms useful for your task.
Use dry_run to inspect the resulting quote before fetching.
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
`query`	yes	What to search. Plain topics, "quoted phrases", @handles, owner/repo, domains and URLs are each understood.	`model context protocol`
`estimate`	no	true returns the execution plan and maximum cost without running anything. Free.	`true`
`sources`	no	Comma list restricting the fan-out. Default sources (github, hackernews, reddit, bluesky, youtube) run unless excluded; metered sources (tiktok, instagram, linkedin, threads, pinterest, x) run ONLY when named here; free niche lanes (polymarket, google_news) also run only when named. A leg that cannot serve the query kind is skipped with the reason in the receipts. Unknown names are ignored with a warning; 'twitter' is accepted for x.	`github,reddit,tiktok`
`exclude`	no	Comma list of sources to leave out.	`bluesky`
`comments`	no	true fetches the top comments for the top results, cited per item under top_comments — only from sources with a live comment endpoint (reddit, hackernews, youtube; tiktok/instagram when opted in via sources=). Enrichment receipts land in the enrichment section; failures degrade per item.	`true`
`lookback_days`	no	Only results from the last N days, where the source supports it.	`7`
`timeframe`	no	hour \| day \| week \| month \| year \| all — coarse alternative to lookback_days. Accepted values: hour, day, week, month, year, all. Case, spaces, hyphens and underscores are interchangeable.	`week`
`from_date`	no	ISO date lower bound, where the source supports it.	`2026-01-01`
`to_date`	no	ISO date upper bound, where the source supports it.	`2026-03-01`
`stream`	no	1 answers text/event-stream: plan, source-started, source-completed, cost and enrichment progress events as legs actually run, then one final result event carrying the exact envelope a plain call returns — same billing, same receipts.	`1`
`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`
`subject_match`	no	Set context for Conversations discovery across explicitly selected sources.	`context`
`subject_context`	no	Optional subject meaning, up to 240 characters. Requires subject_match=context.	`authentication software`
`cursor`	no	Opaque continuation from a context search. Keep the original query, sources, context and date settings.

Examples

Make the request

curl

curl "https://www.monocrawl.com/v1/search/all?query=model%20context%20protocol" \
  -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/search/all?query=model%20context%20protocol",
  { 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/search/all?query=model%20context%20protocol",
    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": "search",
  "endpoint": "/v1/search/all",
  "data": {
    "_meta": {
      "billing": {
        "charged": 0,
        "formula": "example",
        "list_price": 0
      },
      "intent": {
        "kind": "example",
        "terms": [
          "example"
        ],
        "value": "example"
      },
      "mosaic_version": "example",
      "queries": {
        "bluesky": "example",
        "github": "example",
        "hackernews": "example",
        "reddit": "example",
        "youtube": "example"
      },
      "ranking": {
        "formula": "example",
        "min_relevance": 0,
        "source_weights": {
          "bluesky": 0,
          "github": 0,
          "hackernews": 0,
          "reddit": 0,
          "youtube": 0
        }
      },
      "timings": {
        "total_ms": 0
      }
    },
    "_warnings": [
      "example"
    ],
    "clusters": [
      {
        "item_indices": [
          0
        ],
        "label": "example",
        "size": 0,
        "sources": [
          "example"
        ]
      }
    ],
    "count": 0,
    "divergence": {
      "notes": [
        {
          "detail": "example",
          "formula": "example",
          "kind": "example"
        }
      ],
      "per_source": [
        {
          "items": 0,
          "median_relevance": 0,
          "newest_at": "2026-09-01T12:00:00Z",
          "source": "example",
          "top_engagement": 0
        }
      ]
    },
    "dropped_below_floor": 0,
    "items": [
      {
        "also_seen_on": [
          "example"
        ],
        "author": "example",
        "author_association": "example",
        "body": "example",
        "cid": "example",
        "closed_at": "2026-09-01T12:00:00Z",
        "comments": 0,
        "comments_count": 0,
        "confidence": {
          "reasons": [
            "example"
          ],
          "score": 0
        },
        "created_at": "2026-09-01T12:00:00Z",
        "embed_type": "example",
        "hn_url": "https://example.com/example",
        "id": "example",
        "indexed_at": "2026-09-01T12:00:00Z",
        "is_pull_request": false,
        "is_reply": false,
        "labels": [
          "example"
        ],
        "langs": [
          "example"
        ],
        "likes": 0,
        "number": 0,
        "points": 0,
        "quotes": 0,
        "reactions": 0,
        "replies": 0,
        "reposts": 0,
        "rkey": "example",
        "source": "example",
        "state": "example",
        "story_id": "example",
        "text": "example",
        "title": "example",
        "type": "example",
        "updated_at": "2026-09-01T12:00:00Z",
        "url": "https://example.com/example"
      }
    ],
    "outcome": "example",
    "query": "example",
    "sources": [
      {
        "error": "example",
        "items_found": 0,
        "items_kept": 0,
        "latency_ms": 0,
        "reason": "example",
        "served_by": "example",
        "source": "example",
        "status": "example"
      }
    ],
    "sources_attempted": 0,
    "sources_searched": 0
  },
  "credits_used": 10,
  "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
`_meta`	`object \| null`	Optional meta supplied by this operation. Null means unknown.
`_meta.billing`	`object \| null`	Optional billing supplied by this operation. Null means unknown.
`_meta.billing.charged`	`number \| null`	Optional charged supplied by this operation. Null means unknown.
`_meta.billing.formula`	`string \| null`	Optional formula supplied by this operation. Null means unknown.
`_meta.billing.list_price`	`number \| null`	Optional list price supplied by this operation. Null means unknown.
`_meta.intent`	`object \| null`	Optional intent supplied by this operation. Null means unknown.
`_meta.intent.kind`	`string \| null`	Optional kind supplied by this operation. Null means unknown.
`_meta.intent.terms`	`array \| null`	Optional terms supplied by this operation. Null means unknown.
`_meta.intent.value`	`string \| null`	Optional value supplied by this operation. Null means unknown.
`_meta.mosaic_version`	`string \| null`	Optional mosaic version supplied by this operation. Null means unknown.
`_meta.queries`	`object \| null`	Optional queries supplied by this operation. Null means unknown.
`_meta.queries.bluesky`	`string \| null`	Optional bluesky supplied by this operation. Null means unknown.
`_meta.queries.github`	`string \| null`	Optional github supplied by this operation. Null means unknown.
`_meta.queries.hackernews`	`string \| null`	Optional hackernews supplied by this operation. Null means unknown.
`_meta.queries.reddit`	`string \| null`	Optional reddit supplied by this operation. Null means unknown.
`_meta.queries.youtube`	`string \| null`	Optional youtube supplied by this operation. Null means unknown.
`_meta.ranking`	`object \| null`	Optional ranking supplied by this operation. Null means unknown.
`_meta.ranking.formula`	`string \| null`	Optional formula supplied by this operation. Null means unknown.
`_meta.ranking.min_relevance`	`number \| null`	Optional min relevance supplied by this operation. Null means unknown.
`_meta.ranking.source_weights`	`object \| null`	Optional source weights supplied by this operation. Null means unknown.
`_meta.ranking.source_weights.bluesky`	`number \| null`	Optional bluesky supplied by this operation. Null means unknown.
`_meta.ranking.source_weights.github`	`number \| null`	Optional github supplied by this operation. Null means unknown.
`_meta.ranking.source_weights.hackernews`	`number \| null`	Optional hackernews supplied by this operation. Null means unknown.
`_meta.ranking.source_weights.reddit`	`number \| null`	Optional reddit supplied by this operation. Null means unknown.
`_meta.ranking.source_weights.youtube`	`number \| null`	Optional youtube supplied by this operation. Null means unknown.
`_meta.timings`	`object \| null`	Optional timings supplied by this operation. Null means unknown.
`_meta.timings.total_ms`	`number \| null`	Optional total ms supplied by this operation. Null means unknown.
`_warnings`	`array \| null`	Optional warnings supplied by this operation. Null means unknown.
`clusters`	`array \| null`	Optional clusters supplied by this operation. Null means unknown.
`clusters[].item_indices`	`array \| null`	Optional item indices supplied by this operation. Null means unknown.
`clusters[].label`	`string \| null`	Optional label supplied by this operation. Null means unknown.
`clusters[].size`	`number \| null`	Optional size supplied by this operation. Null means unknown.
`clusters[].sources`	`array \| null`	Optional sources supplied by this operation. Null means unknown.
`count`	`number \| null`	Number of records in this response, not lifetime or total matches.
`divergence`	`object \| null`	Optional divergence supplied by this operation. Null means unknown.
`divergence.notes`	`array \| null`	Optional notes supplied by this operation. Null means unknown.
`divergence.notes[].detail`	`string \| null`	Optional detail supplied by this operation. Null means unknown.
`divergence.notes[].formula`	`string \| null`	Optional formula supplied by this operation. Null means unknown.
`divergence.notes[].kind`	`string \| null`	Optional kind supplied by this operation. Null means unknown.
`divergence.per_source`	`array \| null`	Optional per source supplied by this operation. Null means unknown.
`divergence.per_source[].items`	`number \| null`	Returned records. Source coverage and completeness vary.
`divergence.per_source[].median_relevance`	`number \| null`	Optional median relevance supplied by this operation. Null means unknown.
`divergence.per_source[].newest_at`	`string \| null`	Optional newest at supplied by this operation. Null means unknown.
`divergence.per_source[].source`	`string \| null`	Optional source supplied by this operation. Null means unknown.
`divergence.per_source[].top_engagement`	`number \| null`	Optional top engagement supplied by this operation. Null means unknown.
`dropped_below_floor`	`number \| null`	Optional dropped below floor supplied by this operation. Null means unknown.
`items`	`array \| null`	Returned records. Source coverage and completeness vary.
`items[].also_seen_on`	`array \| null`	Optional also seen on supplied by this operation. Null means unknown.
`items[].author`		Public author information supplied with this record.
`items[].author_association`	`string \| null`	Optional author association supplied by this operation. Null means unknown.
`items[].body`	`string \| null`	Optional body supplied by this operation. Null means unknown.
`items[].cid`	`string \| null`	Optional cid supplied by this operation. Null means unknown.
`items[].closed_at`	`string \| null`	Optional closed at supplied by this operation. Null means unknown.
`items[].comments`	`number \| null`	Optional comments supplied by this operation. Null means unknown.
`items[].comments_count`	`number \| null`	Optional comments count supplied by this operation. Null means unknown.
`items[].confidence`	`object \| null`	Optional confidence supplied by this operation. Null means unknown.
`items[].confidence.reasons`	`array \| null`	Optional reasons supplied by this operation. Null means unknown.
`items[].confidence.score`	`number \| null`	Optional score supplied by this operation. Null means unknown.
`items[].created_at`	`string \| null`	Source creation time, not the API retrieval time.
`items[].embed_type`	`string \| null`	Optional embed type supplied by this operation. Null means unknown.
`items[].hn_url`	`string \| null`	Optional hn url supplied by this operation. Null means unknown.
`items[].id`		Source identifier. Preserve the supplied type and exact value.
`items[].indexed_at`	`string \| null`	Optional indexed at supplied by this operation. Null means unknown.
`items[].is_pull_request`	`boolean \| null`	Optional is pull request supplied by this operation. Null means unknown.
`items[].is_reply`	`boolean \| null`	Optional is reply supplied by this operation. Null means unknown.
`items[].labels`	`array \| null`	Optional labels supplied by this operation. Null means unknown.
`items[].langs`	`array \| null`	Optional langs supplied by this operation. Null means unknown.
`items[].likes`	`number \| null`	Optional likes supplied by this operation. Null means unknown.
`items[].number`	`number \| null`	Optional number supplied by this operation. Null means unknown.
`items[].points`	`number \| null`	Optional points supplied by this operation. Null means unknown.
`items[].quotes`	`number \| null`	Optional quotes supplied by this operation. Null means unknown.
`items[].reactions`	`number \| null`	Optional reactions supplied by this operation. Null means unknown.
`items[].replies`	`number \| null`	Optional replies supplied by this operation. Null means unknown.
`items[].reposts`	`number \| null`	Optional reposts supplied by this operation. Null means unknown.
`items[].rkey`	`string \| null`	Optional rkey supplied by this operation. Null means unknown.
`items[].source`	`string \| null`	Optional source supplied by this operation. Null means unknown.
`items[].state`	`string \| null`	Optional state supplied by this operation. Null means unknown.
`items[].story_id`	`string \| null`	Optional story id supplied by this operation. Null means unknown.
`items[].text`	`string \| null`	Source text when supplied.
`items[].title`	`string \| null`	Source title when supplied.
`items[].type`	`string \| null`	Optional type supplied by this operation. Null means unknown.
`items[].updated_at`	`string \| null`	Optional updated at supplied by this operation. Null means unknown.
`items[].url`	`string \| null`	Original source URL when supplied.
`outcome`	`string \| null`	Optional outcome supplied by this operation. Null means unknown.
`query`	`string \| null`	Optional query supplied by this operation. Null means unknown.
`sources`	`array \| null`	Optional sources supplied by this operation. Null means unknown.
`sources[].error`	`string \| null`	Optional error supplied by this operation. Null means unknown.
`sources[].items_found`	`number \| null`	Optional items found supplied by this operation. Null means unknown.
`sources[].items_kept`	`number \| null`	Optional items kept supplied by this operation. Null means unknown.
`sources[].latency_ms`	`number \| null`	Optional latency ms supplied by this operation. Null means unknown.
`sources[].reason`	`string \| null`	Optional reason supplied by this operation. Null means unknown.
`sources[].served_by`	`string \| null`	Optional served by supplied by this operation. Null means unknown.
`sources[].source`	`string \| null`	Optional source supplied by this operation. Null means unknown.
`sources[].status`	`string \| null`	Optional status supplied by this operation. Null means unknown.
`sources_attempted`	`number \| null`	Optional sources attempted supplied by this operation. Null means unknown.
`sources_searched`	`number \| null`	Optional sources searched 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

Cross-platform Search API

Query parameters

Make the request

Response fields and example

Useful next calls

First call in under a minute