--- title: "Ai Search Status Endpoint" method: GET path: "/api/v1/remy/ai-search/status/{job_id}" tags: ["remy", "remy"] --- # Ai Search Status Endpoint `GET /api/v1/remy/ai-search/status/{job_id}` Poll one search: the reasoning steps so far, and the scored table once it is complete. `steps` grows while the search runs — it is the "Show reasoning" panel, and the first step names what the brief was understood as, which is the only way to tell a misread brief from an empty roster (both render as an empty table). `candidate_count` is exact up to 10,000 and capped beyond it, because an uncapped COUNT over a six-figure match set is a full scan on every search. `account_health` has THREE states — "unknown" means we never measured the account, not that it is dead. Pass `page` or `size` to paginate candidates; omitting both preserves the original full-list response. ## Path parameters - `job_id` string, required ## Query parameters - `page` integer, nullable — One-based result page; omit for the legacy full candidate list. - `size` integer, nullable — Candidates per page; defaults to 20 when page is provided. ## Response `200` Successful Response - AiSearchStatusResponseDTO — One poll. Everything below `steps` is null until status is "completed". - `job_id` string, required - `search_id` string, nullable - `status` string, required - `steps` string[] - `error` string, nullable - `started_at` string, date-time, nullable - `finished_at` string, date-time, nullable - `filters` object, nullable - `depth` string, nullable - `candidate_count` integer, nullable - `candidate_count_capped` boolean, nullable - `narrowed_count` integer, nullable - `requested_count` integer, nullable - `semantic_intent` string, nullable - `selection_plan` AiSearchSelectionPlanDTO - `pools` AiSearchPoolDTO[] - `name` string, required - `dimension` string, required - `values` string[] - `target_count` integer, nullable - `min_count` integer, nullable - `max_count` integer, nullable - `shortlist_count` integer, nullable - `overlap_allowed` boolean - `creator_tier` string, nullable - `creator_profiles` string[] - `required_platforms` string[] - `content_formats` string[] - `duration_seconds_min` integer, nullable - `duration_seconds_max` integer, nullable - `commercial_criteria` AiSearchCommercialCriteriaDTO - `average_cpv_inr` number, nullable - `meta_budget_min_inr` integer, nullable - `meta_budget_max_inr` integer, nullable - `youtube_budget_max_inr` integer, nullable - `engagement_rate_preferred_min` number, nullable - `engagement_rate_preferred_max` number, nullable - `warnings` string[] - `content_search_plan` AiSearchContentSearchPlanDTO — Provider-neutral vocabulary for the upcoming Instagram/YouTube content-search stage. - `queries` string[] - `hashtags` string[] - `live_search_constraints` object[] - `recency_days` integer, required - `live_content_summary` AiSearchLiveContentSummaryDTO - `enabled` boolean - `status` string - `platforms` string[] - `discovered_count` integer - `matched_content_count` integer - `matched_creator_count` integer - `unmatched_content_count` integer - `preview_creator_count` integer - `per_platform` object - `provider_errors` object - `discovery_summary` AiSearchDiscoverySummaryDTO - `raw_posts_credits_used` number - `total_credits_used` number, nullable - `billing_scope` string, nullable - `triggered` boolean - `provider` string - `roster_count` integer - `requested_count` integer, nullable - `fetched_count` integer - `written_count` integer - `credits_used` number - `credits_left` number, nullable - `from_cache` boolean - `status` string - `error` string, nullable - `discovered_creators` AiSearchDiscoveredCreatorPreviewDTO[] - `country` string, nullable - `languages` string[] - `niches` string[] - `posts_billing` object, nullable - `creator_id` string, required - `platform` string, required - `handle` string, nullable - `display_name` string, nullable - `url` string, nullable - `followers` integer, nullable - `engagement_rate` number, nullable - `tier` string, nullable - `profile_pic_url` string, nullable - `saved` boolean - `posts` object, nullable - `score` object, nullable - `pool_summary` AiSearchPoolSummaryDTO[] - `name` string, required - `dimension` string, required - `values` string[] - `target_count` integer, nullable - `min_count` integer, nullable - `max_count` integer, nullable - `shortlist_count` integer, nullable - `matched_count` integer, required - `shortfall` integer, required - `shortfall` string, nullable - `pagination` AiSearchPaginationDTO - `total` integer, required - `page` integer, required - `size` integer, required - `pages` integer, required - `candidates` AiSearchCandidateDTO[] - `creator_id` string, required - `platform` string, nullable - `handle` string, nullable - `display_name` string, nullable - `profile_pic_url` string, nullable - `followers` integer, nullable - `engagement_rate` number, nullable - `niches` string[] - `country` string, nullable - `languages` string[] - `available_platforms` string[] - `creator_locations` string[] - `pool_labels` string[] - `required_platforms_match` boolean, nullable - `last_post_days` integer, nullable - `posts_last_30` integer, nullable - `relevance` number, required - `match_score` integer, required - `match_reasons` string[] - `account_health` string, required - `account_health_reason` string, nullable - `business_email` string, nullable - `content_match_count` integer - `matched_content` AiSearchContentEvidenceDTO[] - `platform` string, required - `platform_content_id` string, required - `content_url` string, nullable - `content_type` string - `creator_platform_id` string, nullable - `creator_handle` string, nullable - `creator_name` string, nullable - `title` string, nullable - `caption` string, nullable - `published_at` string, nullable - `like_count` integer, nullable - `comment_count` integer, nullable - `view_count` integer, nullable - `play_count` integer, nullable - `duration_seconds` integer, nullable - `thumbnail_url` string, nullable - `media_url` string, nullable - `hashtags` string[] - `search_query` string, nullable - `source` string, required ## Other responses - `422` — Validation Error ## Changes > 15 revisions in range; 1 not diffed. - **2026-09-21** `a6cea1834b97` — 9 info - added the optional property `discovered_creators/items/country` to the response with the `200` status - added the optional property `discovered_creators/items/languages` to the response with the `200` status - added the optional property `discovered_creators/items/niches` to the response with the `200` status - added the optional property `discovered_creators/items/posts` to the response with the `200` status - …5 more - **2026-09-16** `dda5cf04b73d` — 1 info - endpoint added [Change history](https://skmtc.dev/brandbooster/apis/fastapi/changes/api/v1/remy/ai-search/status/:job_id/get.md) --- [API](https://skmtc.dev/brandbooster/apis/fastapi.md) · [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc.dev/brandbooster/apis/fastapi/revisions/7ba0627b6b4c?raw)