API
API recipes¶
Five recipes for common jobs, each ready to copy. Only one of them starts a run, and it shows you the price before anything is charged.
Before you start¶
You need an API key, plus curl and jq on the machine that runs the
recipes. The Quickstart shows where to create the key.
Every recipe starts from these four lines. Put your own key and brand in them. A brand is known by its website domain.
export HF_KEY=hf_YOUR_KEY
API=https://app.tryremake.com/v1
AUTH="Authorization: Bearer $HF_KEY"
BRAND=samsung.com
Export Visibility every week¶
Goal: write each brand's latest Visibility to a CSV file, once a week.
#!/bin/sh
# visibility.sh: the latest Visibility of every brand, as CSV
API=https://app.tryremake.com/v1
AUTH="Authorization: Bearer $HF_KEY"
echo "domain,date,visibility,mentions,asked"
curl -s "$API/workspaces?limit=200" -H "$AUTH" |
jq -r '.items[].brands[] | select(.domain != "") | .domain' |
while read -r DOMAIN; do
curl -s "$API/brands/$DOMAIN/visibility" -H "$AUTH" |
jq -r --arg d "$DOMAIN" '.points[-1] // empty
| [$d, .date, .rate, .mentions, .asked] | @csv'
done
Run it every Monday at 07:00 with a cron line like this one:
0 7 * * 1 HF_KEY=hf_YOUR_KEY /path/to/visibility.sh > /path/to/visibility-$(date +\%F).csv
pointslists up to 24 runs, oldest first, sopoints[-1]is the latest.rateis Visibility in whole percent:mentionsanswers named you, out ofasked.- Brands with no runs yet are skipped.
- Past 100 brands, add
sleep 1inside the loop. An account may make 120 calls a minute.
Cost: nothing. It only reads stored results.
Start a run and wait¶
Goal: run a brand's schedule once, now, and stop when the run is over.
# 1. Ask for a quote. Nothing runs, and nothing is charged.
QUOTE=$(curl -s -X POST "$API/brands/$BRAND/prompt-spend/run-now" -H "$AUTH")
echo "$QUOTE" | jq '{price_mills, balance_mills, would_refuse}'
# 2. Confirm with the quote's token and a request id of your own.
BODY=$(echo "$QUOTE" | jq --arg r "run-$(date +%F)" \
'{confirm: true, request_id: $r, quote_token: .quote_token}')
ANSWER=$(curl -s -X POST "$API/brands/$BRAND/prompt-spend/run-now" \
-H "$AUTH" -H "Content-Type: application/json" -d "$BODY")
RUN=$(echo "$ANSWER" | jq -r '.run_id // empty')
[ -n "$RUN" ] || { echo "$ANSWER"; exit 1; }
# 3. Poll until the run is done or failed.
while :; do
STATUS=$(curl -s "$API/brands/$BRAND/runs/$RUN" -H "$AUTH" | jq -r .status)
echo "$STATUS"
case "$STATUS" in done|failed) break ;; esac
sleep 30
done
- The brand needs a schedule on Budget & Spending. Without one, the quote answers
404. - If
would_refuseis notnull, the confirm will fail for that reason. Fix it first. - A quote lasts 30 minutes and confirms one run only.
- Sending the same
request_idagain within 24 hours returns the first answer. It never starts a second run. - Runs take several minutes, so polling every 30 seconds is plenty.
- Prefer a push? A plain webhook channel gets
scan_completewhen the run ends, as Webhooks explains. - The run takes the place of the next scheduled run. The schedule then runs again one interval from now.
Cost: one run at the quoted price; the quote, the confirm and every poll are free. price_mills is in thousandths
of a dollar. Each ask is charged as it runs, and asks that fail on our
side are refunded.
List rivals and their share¶
Goal: see who AI models recommend beside you, and how much of the talk each one gets.
curl -s "$API/brands/$BRAND/dashboard" -H "$AUTH" |
jq -r '.trend.series[]? | [.name, .sov[-1], .mentions[-1]] | @tsv'
Each line is a name, its share of voice in the latest run, and the answers that named it. The first line is you.
trend.series holds you
plus up to 5 rivals in the order they were first seen, with one value per run, oldest first.
Its share of voice comes from the stored rival list, so it can differ slightly from Insights.
Rivals are businesses only: a city, region or country an answer names is left out of trend.series and league.
Shares are taken over businesses alone, and a rival you added yourself is always listed.
Since 1 November 2026 this also applies to runs stored before that date.
For every rival in the latest run, with the change since the run before:
curl -s "$API/brands/$BRAND/dashboard" -H "$AUTH" |
jq -r '.league[] | [.name, .appearances, .delta] | @tsv'
Share of voice explains how the share is counted.
Cost: nothing. It only reads stored results.
Pull a prompt's latest answers¶
Goal: read what each AI model said to one prompt in the latest finished run.
PROMPT="best phone camera for low light"
RUN=$(curl -s "$API/brands/$BRAND/runs?limit=20" -H "$AUTH" |
jq -r '[.items[] | select(.status == "done")][0].token')
OFFSET=0
while :; do
PAGE=$(curl -s "$API/brands/$BRAND/runs/$RUN/answers?limit=200&offset=$OFFSET" -H "$AUTH")
echo "$PAGE" | jq --arg q "$PROMPT" \
'.answers[] | select(.prompt == $q) | {ai_model, verdict, cited, answer}'
OFFSET=$((OFFSET + 200))
[ "$OFFSET" -lt "$(echo "$PAGE" | jq .total)" ] || break
done
- The runs list comes newest first, so the first
donerun is the latest finished one. - The prompt must match the stored text exactly.
GET /v1/brands/{brand}/promptslists it underitems[].q. verdictruns from best to worst:cited(your site was a source),lead(named early),named, thenmiss.- A page holds up to 200 answers, so the loop follows
offsetuntil it reachestotal.
Cost: nothing. It only reads stored results.
Send alerts to Slack¶
Goal: get a Slack message when a brand's numbers move.
This needs no code. Open the Alerts tab of Integrations. Pick Webhook (HTTPS), paste your Slack incoming-webhook URL and click Add channel.
remake recognises the address and posts a formatted Slack message. Webhooks lists every event, and Alerts covers email and the weekly digest.
Cost: none. Alerts spend nothing from your wallet.
FAQ¶
Can I start a one-off run through the API?¶
No. The API runs a brand's schedule once, the same as Run now in the app. Set up the schedule on Budget & Spending first.
Is there a webhook when my run finishes?¶
Yes, for the run you start here. A plain webhook channel on your account
gets scan_complete when it ends, so you can skip the polling.
Webhooks shows what it sends.
Why do I get a 429?¶
Your account made more than 120 calls in 60 seconds, across all its keys
and connected apps. Wait the seconds given in the Retry-After header,
then carry on; nothing is charged for a refused call.
Keys, limits and errors has every error code.
Related¶
Create or revoke keys in Your AI › API keys.