---
title: "Queue a new keyword search job"
method: POST
path: "/v1/orbit"
tags: ["Orbit"]
---

# Queue a new keyword search job

`POST /v1/orbit`

## Request

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

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

## Request body

- V1QueueKeywordSearchDto
  - `name` string, required: Name for this keyword search
  - `keywords` string[], required: Array of keywords to search for (max 10)
  - `platforms` string[]: Platforms to scrape from
  - `min_views` number: [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_analysis` boolean: [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_ads` boolean: Enable Meta ads collection for this search
  - `exclude_keywords` string[]: 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_strict` boolean: 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.
  - `intent` string: Intent or purpose for this keyword search
  - `data_intelligence_enabled` boolean: 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_only` boolean: When true (default), only English-language content is collected. Set false to collect content in any language.

## Response `202`

Job queued successfully

- QueueOrbitResponseDto
  - `data` QueueOrbitDataDto, required
    - `orbit_id` string, required
    - `status` string, required
    - `message` string, required

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - missing or invalid API key
- `429`: Too many requests - rate limit exceeded

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)