Research previews

A research preview is a cheap, capped sample of a search — a live SERP/profile snapshot plus a volume estimate — so you can validate a query before committing to a full dataset run. Each preview persists and can be retrieved later by id. Resources are scoped to the account that owns the API key.

Endpoints

curl -X POST "https://example.com/v1/research_previews" \  -H "Content-Type: application/json" \  -d '{    "type": "prompt",    "search_query": "string",    "sources": [      "string"    ]  }'

{
  "status": "info",
  "data": {
    "preview_id": "string",
    "estimated_number_of_results": 0,
    "posts": [
      {
        "position": 0,
        "source": "string",
        "url": "string",
        "author_display_name": "string",
        "headline": "string",
        "relative_date": "string",
        "text": "string",
        "is_image_available": true
      }
    ],
    "type": "prompt"
  }
}

{
  "status": "info",
  "error_code": "insufficient_credits_research_preview",
  "detail": "string",
  "transient": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

curl -X GET "https://example.com/v1/research_previews/string"

null

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Preview types

POST /v1/research_previews accepts a tagged-union body discriminated on type:

• { "type": "prompt", "search_query": "...", "sources": [...] } — keyword search across one or more of reddit, tiktok, youtube, instagram, linkedin. Returns estimated_number_of_results and a sample of posts.
• { "type": "url", "source_urls": [...] } — direct profile/URL scraping. Returns the profiles that resolved, plus failed_to_retrieve_profiles, non_existing_profiles, and private_profiles for the URLs that returned no data.

Both variants accept an optional time window, language, and country_code. See the schemas above for exact fields and bounds.

Time window (prompt)

A prompt preview takes exactly one time window — either a relative time_filter or an absolute date_since + date_until pair, never both and never neither. Supplying both, or an incomplete absolute pair, fails validation with 422. (url previews use date_filter_since / date_filter_until.)

Per-source pricing

Previews charge 1 credit per source, held as a single reservation up front and finalized to the billable count:

• prompt — source_count = len(sources) (the platforms searched). All platforms are queried, so the full amount is charged; there is no partial refund.
• url — source_count = len(source_urls) (each URL is a separate scrape). Only the URLs that return data are billable: any URL that is private, non-existing, or failed to retrieve is refunded. A 6-URL preview where 2 came back empty is charged 4.

If the request would exceed your balance, the endpoint returns 402 insufficient_credits_research_preview before any scraping — you are never partially charged. If the scrape itself fails, the full reservation is refunded.

From preview to a dataset run

A preview de-risks a run: check estimated_number_of_results (or the returned profiles) and the sample before committing credits to a full collection. When the shape looks right, launch a dataset run with the same search_query parameters (sources / source_urls, time window, country_code, language) via POST /v1/datasets/{dataset_id}/runs.

Hold onto the returned preview_id to re-fetch the sample any time with GET /v1/research_previews/{preview_id} — a free DB read (no re-scrape), scoped to your account. A preview_id that belongs to another account, or does not exist, returns 404.

Next steps

• Datasets — commit a validated search to a full, paid collection run.
• Pricing — the per-source model and reservation-based charging behind previews.