Refresh a research's videos

Sweeps fresh metrics for the videos a research serves, so you can see which of them kept growing. Afterwards as_of=latest on any research read serves these numbers; as_of=run is untouched, byte for byte, because nothing rewrites what the research recorded. It is a run rather than a flag on the reads because it fetches every video again from its source and reads must stay free. Only TikTok videos can be refreshed today: videos on other platforms are left out of the quote, the sweep and the charge, and keep the numbers the research recorded; a research with no TikTok videos is refused with 400 unsupported_platform, and a research that serves no videos at all with 400 invalid_request, both before any run opens. One item per video, each with its own status: videos that fail are not charged, some failing makes the run partial, all failing makes it failed and charges nothing. If the Balance runs short by the time the sweep settles, the videos that came back are charged in order up to the Balance and the rest fail with insufficient_balance, leaving the run partial. A retried request with the same Idempotency-Key returns the original run and is not charged again; send a new key for a later sweep. The snapshots are stored, so every later call about those videos — yours or anyone's — starts from them.

Open in Playground(no API Key needed)

Price

3 credits per video that comes back.

Supports estimate=true: the reply is the price in Credits and whether it would be cached, with no Run created and nothing charged.

A cached result costs the same as a fresh one; cached says which you got.

Parameters

Responses

200 OK

The sweep finished inside the wait budget: { run, result }. The example is a partial run — two of the fifty videos have been deleted since the research ran, so forty-eight were swept and charged for. With estimate=true, { estimate_credits, cached, videos, per_video_credits, max_estimate_credits, note } instead: videos is how many will be swept, max_estimate_credits equals estimate_credits because a video that fails is not charged, and note says so — and, when some of the research's videos are on a platform that cannot be refreshed yet, how many are left out.

{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "research_refresh",
    "status": "partial",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 144,
    "list_price_credits": 150,
    "cached": false
  },
  "result": {
    "research_id": "run_c07a41bb92",
    "requested": 50,
    "refreshed": 48,
    "failed": 2,
    "per_video_credits": 3,
    "note": "Frozen reads are unchanged. `as_of=latest` now serves these snapshots."
  }
}

{
  "estimate_credits": 150,
  "cached": false,
  "videos": 50,
  "per_video_credits": 3,
  "max_estimate_credits": 150,
  "note": "A video we cannot fetch is not charged, so the final charge is at or below this quote."
}

202 Accepted

Still running: { run }. Poll GET /v1/runs/{id}.

{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "research_refresh",
    "status": "running",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": null,
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  }
}

400 Bad Request

invalid_request (a malformed id, wait, estimate or Idempotency-Key) or unsupported_platform, refused before any Run opens. Nothing is charged.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`estimate` must be `true` or `false`."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console."
}

402 Payment Required

insufficient_balance — the Balance cannot cover the quoted price (the worst case for Research and enriched search). No Run is created and nothing is charged. A multi-item Run whose Balance runs short later charges its completed items up to the Balance and ends partial.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance does not cover this operation. Top up in the console.",
  "balance_credits": 0,
  "required_credits": 150
}

404 Not Found

not_found.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No research with that id for this Customer."
}

409 Conflict

run_not_ready — the research is still running, or failed with nothing to serve. If it is still running, poll GET /v1/runs/{id} and refresh once it settles; a failed research never becomes readable. Also idempotency_conflict — the same Idempotency-Key sent for a different research.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/run_not_ready",
  "title": "Run not ready",
  "status": 409,
  "code": "run_not_ready",
  "detail": "Research `run_c07a41bb92` is still running. Poll GET /v1/runs/run_c07a41bb92 until it reaches a terminal status."
}

429 Too Many Requests

rate_limit_exceeded or concurrency_limit_exceeded, with Retry-After.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "60 requests per minute per key. Retry after the number of seconds in `Retry-After`.",
  "limit": 60
}

502 Bad Gateway

A Run that opened and then failed is answered as application/problem+json with its problem's status — vendor_error here, not_found as 404 — and the Run envelope alongside, so the Run id is kept. A failed Run is never charged.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/vendor_error",
  "title": "Vendor error",
  "status": 502,
  "code": "vendor_error",
  "detail": "The upstream data provider could not be reached.",
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "research_refresh",
    "status": "failed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  }
}

503 Service Unavailable

source_unavailable: every source this Run reads failed or is switched off. The Run fails uncharged, with its envelope alongside; endpoints names the source. Retry later rather than treating it as empty.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/source_unavailable",
  "title": "Source unavailable",
  "status": 503,
  "code": "source_unavailable",
  "detail": "The tiktok/video source is unavailable right now.",
  "endpoints": [
    "tiktok/video"
  ],
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "research_refresh",
    "status": "failed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  }
}

Request samples

curl -X POST "https://www.shortsintel.com/v1/research/id_example/refresh?wait=30" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/research/id_example/refresh?wait=30",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.post(
    "https://www.shortsintel.com/v1/research/id_example/refresh?wait=30",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

Related guides

This call creates a Run. With wait it holds the response open until the Run finishes or the wait runs out, then answers with the finished result or 202 and the running Run. Poll GET /v1/runs/{id} until it settles; re-reading a Run is free.

• Runs: How a call becomes a Run, waiting inline, polling and free re-reads.
• Pricing and estimates: Credits, estimates and why a cached result costs the same as a fresh one.
• Research: How an intent becomes a digest, why a research id is a run id, and how to re-slice what you collected for free instead of paying for it twice.