# Mosaic API guide ## Choose a Mosaic operation Start with the object your task needs. The groups below use the current catalogue; open an endpoint to check accepted identifiers, filters, price and availability before retrieving. ### Other operations - [Cross-platform search](https://www.monocrawl.com/docs/endpoints/search/all) — 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. - [Creator search](https://www.monocrawl.com/docs/endpoints/search/creators) — Cross-platform creator discovery over TikTok, Instagram and Threads: unified creator cards with reach, verification and per-card evidence (Threads creators are derived from matching posts and cite them). Every leg is metered, so the flagship fair-use ceiling applies; no creators found charges 0 and failed legs prorate. - [Forum search](https://www.monocrawl.com/docs/endpoints/search/forums) — Fused forum search across Reddit and Hacker News, merged into one tagged result list. Naver is listed in sources_unavailable pending a keyed official API. ## Check fields and collection limits Use the endpoint’s declared parameters and returned continuation. Filters from another platform do not automatically apply here. Preserve source identifiers, URLs and warnings; a successful page does not establish complete history. Published response schemas identify whether they come from a reviewed shaper or observed response shapes. Agents can use `get_endpoint` for the current contract and `get_docs` with topic `platforms/search` to read this page. The [coverage guide](https://www.monocrawl.com/docs/data-availability) explains nulls and partial results, and the [production guide](https://www.monocrawl.com/docs/production-checklist) covers budgets and recovery. ## Endpoint reference ## search/all `GET /v1/search/all` 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. *Cross-platform search* | Parameter | Required | Description | | --- | --- | --- | | `query` | yes | What to search. Plain topics, "quoted phrases", @handles, owner/repo, domains and URLs are each understood. — e.g. `model context protocol` | | `estimate` | no | true returns the execution plan and maximum cost without running anything. Free. — e.g. `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. — e.g. `github,reddit,tiktok` | | `exclude` | no | Comma list of sources to leave out. — e.g. `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. — e.g. `true` | | `lookback_days` | no | Only results from the last N days, where the source supports it. — e.g. `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. — e.g. `week` | | `from_date` | no | ISO date lower bound, where the source supports it. — e.g. `2026-01-01` | | `to_date` | no | ISO date upper bound, where the source supports it. — e.g. `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. — e.g. `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. — e.g. `1` | | `subject_match` | no | Set context for Conversations discovery across explicitly selected sources. — e.g. `context` | | `subject_context` | no | Optional subject meaning, up to 240 characters. Requires subject_match=context. — e.g. `authentication software` | | `cursor` | no | Opaque continuation from a context search. Keep the original query, sources, context and date settings. | ### 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. **Cost:** 10 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/search/all?query=model%20context%20protocol" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "_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 } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/search/all#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/search/all.json) ## search/creators `GET /v1/search/creators` Cross-platform creator discovery over TikTok, Instagram and Threads: unified creator cards with reach, verification and per-card evidence (Threads creators are derived from matching posts and cite them). Every leg is metered, so the flagship fair-use ceiling applies; no creators found charges 0 and failed legs prorate. *Creator search* | Parameter | Required | Description | | --- | --- | --- | | `query` | yes | Who to look for — a niche, a name, a topic. — e.g. `barefoot running` | | `sources` | no | Comma list restricting the fan-out: tiktok, instagram, threads (default all three). — e.g. `tiktok,instagram` | | `estimate` | no | true returns the plan and maximum cost without running anything. Free. — e.g. `true` | | `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. — e.g. `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. — e.g. `1` | ### Useful optional inputs - `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. **Cost:** 10 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/search/creators?query=barefoot%20running" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "items": [], "count": 0 } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/search/creators#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/search/creators.json) ## search/forums `GET /v1/search/forums` Fused forum search across Reddit and Hacker News, merged into one tagged result list. Naver is listed in sources_unavailable pending a keyed official API. *Forum search* | Parameter | Required | Description | | --- | --- | --- | | `query` | yes | Search phrase — e.g. `rust async runtime` | | `sources` | no | Comma list restricting which forums are searched — e.g. `reddit,hackernews` | | `exclude` | no | Comma list of forums to skip — e.g. `hackernews` | | `comments` | no | Reserved — inline comments are not supported yet — e.g. `top` | | `timeframe` | no | hour \| day \| week \| month \| year \| all Accepted values: hour, day, week, month, year, all. Case, spaces, hyphens and underscores are interchangeable. — e.g. `week` | | `lookback_days` | no | Only results from the last N days, where the source supports it — e.g. `30` | | `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. — e.g. `1` | ### 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. **Cost:** 10 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/search/forums?query=rust%20async%20runtime" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "_warnings": [ "example" ], "count": 0, "items": [ { "author": "example", "comments_count": 0, "created_at": "2026-09-01T12:00:00Z", "hn_url": "https://example.com/example", "id": "example", "points": 0, "source": "example", "story_id": "example", "text": "example", "title": "example", "type": "example", "url": "https://example.com/example" } ], "query": "example", "sources": [ { "count": 0, "error": "example", "ok": false, "served_by": "example", "source": "example" } ], "sources_unavailable": [ "example" ] } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/search/forums#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/search/forums.json)