# Monthly report (/docs/recipes/monthly-report) Collect last month's posts about several products or brands in one run, with each post's stance, and turn them into a summary table each month Send one request with a group for each product or brand you compare. You get back last month's posts for each group, with every post's stance, and a count per group. Put the same request on a monthly schedule and the report builds itself. The example compares oat milk, almond milk and soy milk. Measured on 18/11/2026: one run for October 2026 kept 171 posts across the three groups, each with its stance, for 18 credits. Half of that paid for the searches and half for the stance labels. ## Start in five minutes Set your key once. Every block on this page reads it. ```bash title="Terminal" export SOCIALCRAWL_API_KEY=YOUR_API_KEY ``` Paste this prompt into your coding agent: ```text title="Prompt" Read https://www.socialcrawl.dev/docs/recipes/monthly-report.md and follow it to build last month's report on oat milk, almond milk and soy milk. Use the key in SOCIALCRAWL_API_KEY. Price the request with a dry run first ("dry_run": true, which is free), and show me the estimate. Send max_credits=60, and ask me before you create a schedule. ``` Or price it yourself. A dry run plans the searches and quotes them for 0 credits: ```bash title="cURL" curl -X POST "https://www.socialcrawl.dev/v1/prism/discover" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ -H "content-type: application/json" \ -d '{"groups":[{"id":"oat-milk","keywords":["oat milk"]},{"id":"almond-milk","keywords":["almond milk"]},{"id":"soy-milk","keywords":["soy milk"]}],"platforms":["reddit","youtube","news"],"period":"last_month","label":["stance"],"limit":50,"max_credits":60,"dry_run":true}' ``` On 18/11/2026 it quoted about 18 credits, at most 45. ## How it works - Each group is one product or brand, searched on every platform you list. - `period=last_month` keeps the posts of the last calendar month, so every report covers the same span. - Each kept post is judged for its stance toward its group's keywords. - A post that two groups both found is kept once, under the first group. - The run works in the background. You follow it, then download every row in one file. ## What you need | Call | What it gives | Credits | | --- | --- | --- | | `POST /v1/prism/discover` with `dry_run` | The plan and the price | 0 | | `POST /v1/prism/discover` | The run, in the background | Each search at its platform's price, plus 1 per started 25 posts for `stance`, up to `max_credits` | | `GET /v1/prism/discover/runs/{run_id}/results.jsonl` | Every row, one per line | 0 | ## Steps ### Step 1: start the run Send the same body without `dry_run`. It answers `202` at once, with the run and its `status_url`. **cURL** ```bash title="cURL" curl -X POST "https://www.socialcrawl.dev/v1/prism/discover" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ -H "content-type: application/json" \ -d '{"groups":[{"id":"oat-milk","keywords":["oat milk"]},{"id":"almond-milk","keywords":["almond milk"]},{"id":"soy-milk","keywords":["soy milk"]}],"platforms":["reddit","youtube","news"],"period":"last_month","label":["stance"],"limit":50,"max_credits":60}' ``` **Python** ```python title="Python" import json, os, urllib.request body = {"groups": [{"id": "oat-milk", "keywords": ["oat milk"]}, {"id": "almond-milk", "keywords": ["almond milk"]}, {"id": "soy-milk", "keywords": ["soy milk"]}], "platforms": ["reddit", "youtube", "news"], "period": "last_month", "label": ["stance"], "limit": 50, "max_credits": 60} req = urllib.request.Request("https://www.socialcrawl.dev/v1/prism/discover", data=json.dumps(body).encode(), headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"], "content-type": "application/json"}) answer = json.load(urllib.request.urlopen(req, timeout=120)) print(answer["data"]["run"]["run_id"], answer["data"]["next"]["status_url"]) ``` - Each group takes its own `keywords`, and can take its own `platforms`, `country` and `languages`. - `limit` is the number of posts kept per group. The POST keeps up to 500 by default. - `max_credits` is required on the POST. The run pauses there and never overspends. ### Step 2: follow it and download the rows Call `status_url` until `data.run.status` is no longer `queued` or `running`. Then download `results.jsonl`. Both reads are free. **Python** ```python title="Python" import json, os, time, urllib.request KEY = {"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]} STATUS_URL = os.environ["STATUS_URL"] # data.next.status_url from step 1 answer = json.load(urllib.request.urlopen(urllib.request.Request(STATUS_URL, headers=KEY), timeout=120)) while answer["data"]["run"]["status"] in ("queued", "running"): time.sleep(10) answer = json.load(urllib.request.urlopen(urllib.request.Request(STATUS_URL, headers=KEY), timeout=120)) run_id = answer["data"]["run"]["run_id"] url = f"https://www.socialcrawl.dev/v1/prism/discover/runs/{run_id}/results.jsonl" with open("rows.jsonl", "wb") as f: f.write(urllib.request.urlopen(urllib.request.Request(url, headers=KEY), timeout=120).read()) for group, g in answer["data"]["summary"]["by_group"].items(): print(group, g["kept"]["delivered"], "posts", g["stance"]) ``` **Terminal** ```bash title="Terminal" curl -sS "https://www.socialcrawl.dev/v1/prism/discover/runs/$RUN_ID/results.jsonl" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" > rows.jsonl ``` Each line of `results.jsonl` is one post, with its `group`, and the last line is `{"complete":true}`. The run's `summary.by_group` holds the counts for your table. On 18/11/2026 it read: | Group | Posts | Positive | Negative | Neutral | No opinion | Uncertain | | --- | --- | --- | --- | --- | --- | --- | | `oat-milk` | 72 | 10 | 7 | 22 | 7 | 26 | | `almond-milk` | 58 | 14 | 4 | 24 | 4 | 12 | | `soy-milk` | 54 | 13 | 0 | 20 | 4 | 17 | The three groups add up to more than 171, because a post that two groups found is counted in both. In `results.jsonl` it appears once, under the first group, with the other in `also_in_groups`. ### Step 3: repeat it every month Add a `schedule` to the same body. The example keeps `dry_run`, so it prices the schedule and creates nothing. Remove `dry_run` to create it. ```bash title="cURL" curl -X POST "https://www.socialcrawl.dev/v1/prism/discover" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ -H "content-type: application/json" \ -d '{"groups":[{"id":"oat-milk","keywords":["oat milk"]},{"id":"almond-milk","keywords":["almond milk"]},{"id":"soy-milk","keywords":["soy milk"]}],"platforms":["reddit","youtube","news"],"period":"last_month","label":["stance"],"limit":50,"schedule":{"every":"30d","max_credits_per_run":60},"dry_run":true}' ``` - Send `start_at` with the first day of next month, so each run covers a whole month. - Each run ends with a `discover.completed` event in the [event feed](/docs/events.md). ## Store only what is new Each monthly run covers a different month, so every row is new to that month's report. Store the rows by month and group, keyed on each post's `url`. To compare months, keep the summary of each month beside the last. A weekly run with `period=7d` on a schedule starts from the last run's watermark, so it returns only posts it has not delivered. ## What it costs | Part | Credits | | --- | --- | | The dry run | 0 | | Each search that returns posts | That platform's search price | | `label=stance` | 1 per started 25 posts | | Following the run and downloading the rows | 0 | | Creating a schedule | 0 | What the example runs measured on 18/11/2026: | Run | Posts | Credits | | --- | --- | --- | | The dry run | 0 | 0 | | The run for October 2026 | 171 | 18 | | The schedule's dry run, every 30 days | 0 | 0 | | The full program straight after, the same body | the same 171 | 0 | The second request found the first run of the same body and returned it, so it cost nothing. ## Tips, and what not to use - Use product categories or large public brands as groups. A brand name that is also an ordinary word needs a `context` that says which meaning you want. - For brands, send `brands` instead of `groups`. Each brand becomes a group and gets the `mention` judgment, which tells a post about the brand from one that only shares its name. - Add `comments=inline` to read the comments under each group's busiest posts. Price it first: it is billed at each platform's comment page price. - Do not run one request per group. One request with groups plans every search together and keeps a post two groups found once. ## Full program and agent brief **Full program (Python)** ```python title="Python" # monthly_report.py: last month's posts about several categories, side by side, as rows.jsonl and summary.csv. # Run on the 1st of each month: SOCIALCRAWL_API_KEY=... python3 monthly_report.py (Python 3.9+, nothing to install) import csv import json import os import time import urllib.request KEY = os.environ["SOCIALCRAWL_API_KEY"] BASE = "https://www.socialcrawl.dev/v1" REPORT = { "groups": [ {"id": "oat-milk", "keywords": ["oat milk"]}, {"id": "almond-milk", "keywords": ["almond milk"]}, {"id": "soy-milk", "keywords": ["soy milk"]}, ], "platforms": ["reddit", "youtube", "news"], "period": "last_month", "label": ["stance"], "limit": 50, "max_credits": 60, } def call(url, body=None): data = json.dumps(body).encode() if body is not None else None req = urllib.request.Request(url, data=data, headers={"x-api-key": KEY, "content-type": "application/json"}) with urllib.request.urlopen(req, timeout=120) as res: return res.read().decode() # 1. Price it. A dry run is free. quote = json.loads(call(f"{BASE}/prism/discover", dict(REPORT, dry_run=True))) print("estimate:", quote["data"]["estimate"]["credits"]) # 2. Start it. It answers 202 with the run; follow status_url until it settles. answer = json.loads(call(f"{BASE}/prism/discover", REPORT)) run = answer["data"]["run"] while run["status"] in ("queued", "running"): time.sleep(10) answer = json.loads(call(answer["data"]["next"]["status_url"])) run = answer["data"]["run"] # 3. Download every row once. Each row sits under one group, the first that found it. lines = call(f"{BASE}/prism/discover/runs/{run['run_id']}/results.jsonl").splitlines() rows = [json.loads(line) for line in lines if line.strip()] rows = [r for r in rows if "url" in r] with open("rows.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps(r) + "\n" for r in rows) # 4. The run's own summary counts each group's posts and stances, shared posts included. STANCES = ["positive", "negative", "neutral", "no_opinion", "uncertain"] with open("summary.csv", "w", newline="", encoding="utf-8") as f: w = csv.writer(f) w.writerow(["group", "posts"] + STANCES) for group, g in answer["data"]["summary"]["by_group"].items(): w.writerow([group, g["kept"]["delivered"]] + [g["stance"].get(k, 0) for k in STANCES]) print(group, g["kept"]["delivered"], {k: g["stance"].get(k, 0) for k in STANCES}) print(f"{len(rows)} rows; run {run['status']}, {run['credits']['spent']} credits") ``` **Agent brief** ```text title="Agent brief" Goal: last month's posts about oat milk, almond milk and soy milk on Reddit, YouTube and news, with stance, as rows.jsonl and summary.csv. Read https://www.socialcrawl.dev/docs/recipes/monthly-report.md first. 1. POST /v1/prism/discover with the page's body and "dry_run": true. Show me data.estimate.credits. 2. Send it without dry_run, with max_credits=60. Follow data.next.status_url until the run settles. 3. Download results.jsonl. Write each row to rows.jsonl, and count posts and stances per group into summary.csv. 4. To repeat it monthly, send the body with schedule every 30d and dry_run true, show me the cost, and create it only when I say so. ``` ## Next steps - [Watch a topic](/docs/recipes/watch-a-topic.md): New posts every few hours instead of once a month. - [Monthly brand report](/docs/prism/discover-brand-report.md): The same report for named brands, with the mention judgment. - [Discover](/docs/engines/discover.md): How Discover searches, judges and schedules.