Research social content with Lightreel

Find social videos, creators, hooks, and trends using Lightreel through your
Scrappycoco account. Describe your task in a question, then review the answer
and supporting sources. Lightreel generates the analysis; you or your AI agent
check whether it answers your question.

Before you start

Connect to Scrappycoco and sign in.
The CLI example below assumes CLI setup is complete.
You use your Scrappycoco account and balance; no Lightreel API key is needed.
Each completed request costs $0.50. Requests can take several minutes.

Ask your connected AI agent

Use Scrappycoco to find three hooks used by fitness apps in the last seven
days. Include the exact hook, source video URL, and date when available.
Tell me where sources or dates are missing.

Your agent can inspect the social capabilities and submit the question. To
build the request yourself, use the example below.

Choose a research task

Use case	Capability	Include in your question
Find winning videos	`social.find_winning_videos`	Account/niche, timeframe, performance criteria, video URLs and metrics
Score and critique accounts	`social.score_accounts`	Account URLs, scoring rubric and examples supporting each score
Discover hooks	`social.discover_hooks`	Product/niche, timeframe, exact hooks and source video URLs
Find micro-influencers	`social.find_micro_influencers`	Platform, follower range, audience, niche and partnerships
Find trending topics	`social.find_trending_topics`	Niche, date window, topic evidence and video URLs
Meta ad inspiration	`social.meta_ad_inspiration`	Product, audience, past creative results and desired formats
Pull contact info for creators	`social.creator_contacts`	Creator criteria, publicly listed business contacts and source URLs

Specify the platform, date range, desired count, and evidence you need in
question. All seven capabilities send your question as written; choosing a
capability does not add filters or scoring rules for you. The top-level limit
does not shorten a Lightreel answer.

Meta ad inspiration uses social videos as creative research. It does not return
a Meta Ad Library feed.

Example: find hooks for a fitness app

Inspect live availability and options first:

scrappycoco catalog list --source social --available --json
scrappycoco catalog inspect social.discover_hooks --json

Save this as request.json:

{
  "source": "social",
  "capability": "discover_hooks",
  "input": {
    "question": "Find three hooks used by fitness apps in the last 7 days. Include exact hook text, source video URL and date when known; explicitly identify evidence gaps."
  },
  "providers": ["lightreel"],
  "provider_options": {
    "lightreel": {
      "response_fields": {
        "hooks": {"type": "array", "description": "One entry per hook with exact text, source video URL and date or unknown."},
        "limitations": {"type": "string", "description": "Missing sources, dates or other limits of the evidence."}
      }
    }
  }
}

Queue the request and copy the returned job_id:

scrappycoco run social.discover_hooks --file request.json --detach --json

Replace JOB_ID below with that ID to wait for the answer and save it:

scrappycoco jobs wait JOB_ID --output hooks.json --json

Open hooks.json and check the returned hooks and sources. Missing dates or
sources should be reported as gaps in the research.

REST and MCP

Submit the same JSON to POST /api/v1/scrapers/jobs, authenticated with
X-API-Key and a unique Idempotency-Key, then retrieve the resulting job.
POST /api/v1/scrapers/execute also accepts it for synchronous execution.
For MCP, use submit_scraper_job with scraper_id: "social.discover_hooks",
the same input, providers and provider_options, plus a unique
idempotency_key. Retrieve the answer with get_job. run_scraper also
supports synchronous execution if your client's timeout is long enough.

All seven actions appear under Social in the tool catalog and Scraper Lab.
Lightreel is currently the only provider for these capabilities. If you want
to test different output options, Discover lets you
compare them and save the configuration you choose.

Read the answer

Each result record contains one complete answer, which may describe several
videos or creators. Plain-text answers are in records[].outputs.text;
structured answers are in records[].outputs.json. The full provider response
is retained in records[].outputs.native_response.

response_fields lets you request one to five named fields, each a string
or array with a description. Omit it for a plain-text answer. If you request
related arrays, explain how their entries should correspond and check the result.

Check the answer against the count, dates, and sources you requested. A status
of ok confirms the request completed; completeness and truncation remain
unknown unless the response supplies evidence. Each new Run starts a fresh
conversation.

Cost and batches

Scrappycoco charges $0.50 per completed request across all seven capabilities.
The charge is per answer, regardless of how many videos, hooks, or creators it
contains. This is Scrappycoco's configured price, not an upstream cost reported
by Lightreel.

Each item in input.items and each Discover comparison candidate is a separate
request with its own charge. There are no automatic retries for Lightreel
requests. Failed or unconfirmed calls do not count as completed requests; a
timeout can leave upstream usage uncertain. See Read results and costs
for billing state.

For more on queued requests, see Jobs and batches.