Social Data

Social Data reads public posts. Two operations:

discover — search a platform by keyword. “What is being said about this?”
collect — fetch posts you already have ids for, optionally with their comment threads.

Not the Social primitive. That one publishes to accounts you own and needs a connected account. This one only reads what is already public, and shares none of its routes.

Platforms

Platform	Provider	Credential	Sync?	`discover` searches	Comments	Transcripts
`bluesky`	the platform’s own public API	none	yes	full text	no	no
`hackernews`	the platform’s own public API	none	yes	full text	yes	no
`x`	Apify actor	`APIFY_API_TOKEN`	yes	full text	no	no
`reddit`	Apify actor	`APIFY_API_TOKEN`	no — batch only	full text	yes	no
`instagram`	Apify actor	`APIFY_API_TOKEN`	no — batch only	hashtag or profile	yes	no
`tiktok`	Apify actor	`APIFY_API_TOKEN`	no — batch only	keyword or hashtag	yes	no
`youtube`	Apify actor	`APIFY_API_TOKEN`	no — batch only	keyword	yes	yes

linkedin is in the shared platform union because the schema is shared with the posting primitive, and is rejected at the routing layer rather than silently returning nothing. An unsupported combination is refused with invalid_input before the provider runs — never served thinner at the same price. Asking Bluesky for comments or TikTok for a transcript is an error, not a quiet omission, because a caller cannot tell an empty comments array caused by a post with no replies from one caused by a platform that never had the capability.

`query` does not mean the same thing everywhere

Search is what each platform gives us, and no amount of normalizing changes that. On X, Reddit, Bluesky and Hacker News a query is full-text search. On Instagram there is no public post search: a query is a hashtag (#agents) or a profile (@openai), and which one is inferred from the prefix. It is read as that exact tag or profile — ai agents reads #aiagents, not a ranked search for the phrase — so a query returns the same feed every time rather than whatever a search engine ranked first. On TikTok and YouTube it is the platform’s own keyword search. Same field, honestly different reach — which is why the response always names the platform it came from.

Four platforms are asynchronous only

A live Reddit run took 53 to 219 seconds to return five posts, and Instagram, TikTok and YouTube drive a headless browser per post. That is not a slow sync case, it is a timeout — and the expensive shape of one, because the actor run bills and the settle completes while the client has already given up and retried. So both sync entry points refuse all four outright, in discover as well as collect, and the refusal names the route that works:

{
  "error": { "code": "invalid_input", "message": "Reddit reads are asynchronous only" },
  "hint": "Submit POST /v1/social-data/tasks with {\"platform\":\"reddit\",\"mode\":\"collect\"} …",
  "details": { "platform": "reddit", "sync_platforms": ["x", "bluesky", "hackernews"] }
}

The CLI and the SDK refuse it before the request leaves the process, and naive_social_* MCP tools do not list any of the four as a sync option at all.

CLI first

# Search public posts
naive social-data discover --platform x --query "ai agents" --limit 25
naive social-data discover --platform hackernews --query "postgres" --engagement-min 50

# Fetch known posts, with their comment threads
naive social-data collect --platform hackernews --post-ids 38975000,38975001 --include-comments

# Reddit, Instagram, TikTok, YouTube — batch only, in either mode
naive social-data batch --platform reddit --mode discover --query "self hosting" --limit 200
naive social-data batch --platform instagram --mode discover --query "#aiagents" --limit 100
naive social-data batch --platform tiktok --mode collect --post-ids 7301...,7302... --include-comments
naive social-data batch --platform youtube --mode discover --query "agent frameworks" --include-transcript
naive social-data task <task-id>

# Governance surfaces, both free
naive social-data terms
naive social-data erase --handle someone

Operations

Operation	Endpoint	Cost (scraped platforms)	Cost (Bluesky / HN)
`discover`	`POST /v1/social-data/{platform}/discover`	3× provider spend	1 credit / 100 posts
`collect`	`POST /v1/social-data/{platform}/collect`	3× provider spend	1, or 2 with comments
`batch`	`POST /v1/social-data/tasks`	3× provider spend	same block rate
`terms`	`GET /v1/social-data/terms`	free	free
`erasure`	`POST /v1/social-data/erasure`	free	free

The scraped platforms bill what they cost, tripled

X, Reddit, Instagram, TikTok and YouTube run through a metered provider, and the meter is 3× the provider spend the run actually incurred — not a per-record list price. So a 20-post Instagram read costs what 20 Instagram rows cost, tripled, and a big YouTube job costs proportionally more instead of paying a block rate that guessed wrong in one direction or the other. provider_usd, whether it was the run’s actual figure or a projection, and the multiplier applied are all recorded on the ledger entry behind every charge.

An empty result is still billed, because the run happened and we were invoiced for it. Scraped search is uneven — the same Reddit query can return three posts or none for the same money — and absorbing that would make an empty answer the cheapest thing to ask for.
A provider failure is not billed: the settle happens after output exists.
Non-zero charges are at least 0.1 credits, the platform-wide minimum.

Before the run, a projection from the actor’s own listed per-event price is reserved against your balance, so an unaffordable job is refused rather than half-run. Bluesky and Hacker News keep a flat rate per block of 100 posts, rounded up, because there is no vendor invoice to multiply — they are the platforms’ own free read APIs. The rate is keyed on the resolved provider, not the platform, so adding a paid provider for one of them later cannot inherit the free price. Not free at all, deliberately: an unmetered endpoint is an unmetered abuse surface. Filters run after the provider does, so they narrow what you receive without narrowing the bill — the run cost what it cost.

discover

curl -X POST https://api.usenaive.ai/v1/social-data/x/discover \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "ai agents", "limit": 25, "filters": {"engagement_min": 100}}'

const { data } = await naive.socialData.discover("x", "ai agents", {
  limit: 25,
  filters: { engagement_min: 100 },
});

Filters are date_from (ISO 8601) and engagement_min. limit caps at 100 — above that, use POST /v1/social-data/tasks.

collect

curl -X POST https://api.usenaive.ai/v1/social-data/hackernews/collect \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"post_ids": ["38975000", "38975001"], "include_comments": true}'

include_comments fetches reply threads. It costs more because it fetches more rows, and on the scraped platforms that shows up directly in the provider spend the charge is derived from. It is not supported everywhere, and where it is not it is refused rather than billed at the higher rate for posts that would arrive without replies:

Platform	`include_comments`
`hackernews`	yes — threads flattened, up to 3 levels deep
`reddit`	yes (batch only)
`instagram`	yes (batch only)
`tiktok`	yes (batch only)
`youtube`	yes (batch only) — a second actor, so comments are billed as their own rows
`bluesky`	refused — replies are a separate thread fetch
`x`	refused — replies are a separate query the actor does not run

include_transcript — YouTube only

include_transcript returns the video’s caption track as plain text on the post, which is what makes YouTube a text source rather than a metadata source: a 40-minute talk becomes something Brain can answer from and Clips can cut against. It is refused on every other platform. TikTok’s provider can transcribe, but it bills per minute of audio rather than per row — a price this primitive’s per-row spend derivation would systematically under-project — so it is not exposed rather than exposed and mis-metered. YouTube’s captions arrive as part of the same billed result, at no extra event cost.

naive social-data batch --platform youtube --mode collect \
  --post-ids dQw4w9WgXcQ --include-transcript

A video with captions disabled returns the post without a transcript. That is a property of the video, not an error, and it is not charged differently.

One shape, seven platforms

{
  "data": [
    {
      "id": "1745...",
      "platform": "x",
      "author": "someone",
      "text": "…",
      "url": "https://x.com/someone/status/1745…",
      "created_at": "2026-02-01T12:00:00Z",
      "metrics": { "likes": 412, "retweets": 55, "comments_count": 18 },
      "comments": []
    }
  ],
  "credits_used": 10,
  "credits_remaining": 4990,
  "provider": "apify"
}

metrics.comments_count is present everywhere; retweets is X-only, upvotes is Reddit-only, and views/plays arrive on the video platforms — absent rather than zeroed elsewhere, so you can tell “none” from “not measured”. Anything the canonical schema does not model stays available under raw, which is where an Instagram carousel’s children or a TikTok’s music metadata live. provider reports which vendor actually served the call — apify, bluesky or hackernews.

prefer_official

Kept in the request contract and still meaningful. For Bluesky and Hacker News it is already satisfied — those are the official APIs. For X, Reddit, Instagram, TikTok and YouTube it is refused explicitly, because claiming a ToS-clean route that does not exist would be worse than saying so.

Batch

POST /v1/social-data/tasks accepts either mode:

curl -X POST https://api.usenaive.ai/v1/social-data/tasks \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"platform": "reddit", "mode": "discover", "query": "self hosting", "limit": 500}'

mode: "discover" requires query; mode: "collect" requires post_ids. Up to PRIMITIVE_BATCH_MAX posts (1,000 by default). Returns 202 — poll GET /v1/social-data/tasks/{id}. Results are pruned at 90 days.

Retries and double-charging

Send an Idempotency-Key header on discover and collect. It deduplicates the response and becomes the credit-ledger reference, so a retried call is not billed twice.

Acceptable use

GET /v1/social-data/terms returns the prohibitions as JSON. Public does not mean unrestricted: posts are personal data, and you are the controller of what you retain. You may not use this primitive to build a personal profile of an individual, to monitor people rather than topics, to identify or track individuals on sensitive characteristics, or to feed employment, credit, insurance or housing decisions. Each platform’s own terms continue to apply to what you do with its content.

Retention and erasure

Sync discover and collect store nothing. Async batch results are the only store, pruned at 90 days.

curl -X POST https://api.usenaive.ai/v1/social-data/erasure \
  -H "Authorization: Bearer nv_sk_your_key" \
  -d '{"handle": "someone"}'

Erasure accepts a handle, email or linkedin and is unmetered.

Erasure clears a subject from Naive’s stored results only. The posts remain public on the platform, and a later collection of the same thread would return them again.

Social — publishing to accounts you own
People — B2B people search and enrichment
Reviews & Listings — local listings and reviews
Data primitive status — what is verified live and what is not

Getting Started

Agent Profiles

Architecture

Primitives

Platforms

`query` does not mean the same thing everywhere

Four platforms are asynchronous only

CLI first

Operations

The scraped platforms bill what they cost, tripled

discover

collect

include_transcript — YouTube only

One shape, seven platforms

prefer_official

Batch

Retries and double-charging

Acceptable use

Retention and erasure

​Platforms

​query does not mean the same thing everywhere

​Four platforms are asynchronous only

​CLI first

​Operations

​The scraped platforms bill what they cost, tripled

​discover

​collect

​include_transcript — YouTube only

​One shape, seven platforms

​prefer_official

​Batch

​Retries and double-charging

​Acceptable use

​Retention and erasure

​Related

Platforms

`query` does not mean the same thing everywhere

Four platforms are asynchronous only

CLI first

Operations

The scraped platforms bill what they cost, tripled

discover

collect

include_transcript — YouTube only

One shape, seven platforms

prefer_official

Batch

Retries and double-charging

Acceptable use

Retention and erasure

Related