Orbit

Queue a new keyword search job

Creates a new keyword search job and queues it for processing.

post/v1/orbit

Request

  • Base URL: https://api.virlo.ai
  • URL: https://api.virlo.ai/v1/orbit
  • Auth: HTTP bearer

Request body

namestring required

Name for this keyword search

keywordsstring[] required

Array of keywords to search for (max 10)

platformsstring[]

Platforms to scrape from

min_viewsnumber

[Deprecated] Previously set the scrape-time minimum view threshold. Collection scope is now system-managed — agents collect the widest relevant net so no content is missed, and you filter by views at READ time on GET /v1/orbit/:orbit_id/videos (min_views). Still accepted for backward compatibility but has NO effect on what gets collected.

time_period'today' | 'this_week' | 'this_month' | 'this_year'

[Deprecated] Previously set the scrape-time publish-date window. Collection scope is now system-managed — agents collect broadly, and you filter by date at READ time on GET /v1/orbit/:orbit_id/videos (start_date / end_date). Still accepted for backward compatibility but has NO effect on what gets collected.

run_analysisboolean

[Deprecated] Previously controlled whether the scraper produced an inline text analysis for this orbit. AI analysis is now generated automatically for every completed orbit via the unified viral_insights pipeline, and is exposed through GET /v1/orbit/:orbit_id/analysis and /trends. This flag is still accepted for backward compatibility but has no effect — it will never be removed.

enable_meta_adsboolean

Enable Meta ads collection for this search

exclude_keywordsstring[]

Noise terms to filter out — matched as WHOLE WORDS against captions + hashtags, so use the single word people actually type for the OTHER meaning (researching Apple the company, not the fruit? exclude recipe, fruit, orchard), not multi-word phrases like apple the fruit (which never match). Never exclude a word that is part of your own topic. Tip: suggest-keywords returns a ready exclude_keywords list you can pass straight in.

exclude_keywords_strictboolean

If true, also match exclude_keywords against the video transcript (speech), not just the caption/hashtags — use when the noise word is spoken but rarely written. Default false.

intentstring

Intent or purpose for this keyword search

data_intelligence_enabledboolean

Enable per-video AI intelligence: 79 structured fields per analyzed video and 70 per analyzed slideshow, covering topics, hooks, sentiment, brand safety, on-screen people and AI provenance. Not every item is analyzed: content that is off-intent, more than a year old (unless among the run's top performers), or that got no more views than its creator has followers is skipped and returns intelligence_status: "skipped". Adds $1.00 (100 credits) to the $0.50 base, so $1.50 per run in total.

english_onlyboolean

When true (default), only English-language content is collected. Set false to collect content in any language.

Example request

{
  "name": "Brainrot Content Analysis",
  "keywords": [
    "Brainrot",
    "Brainrot Content"
  ],
  "platforms": [
    "youtube",
    "tiktok",
    "instagram"
  ],
  "min_views": 30000,
  "time_period": "this_week",
  "run_analysis": true,
  "enable_meta_ads": true,
  "exclude_keywords": [
    "recipe",
    "fruit",
    "orchard"
  ],
  "intent": "Find viral brainrot content for trend analysis"
}

Response

Job queued successfully

Example response

{
  "data": {
    "orbit_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "message": "Keyword search job queued with max priority."
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.