RecruitAffiliates.ai

Start a search

Spends one search credit and starts the search in the background. Poll GET /searches/{id}, then read what it found with GET /prospects. If the search can't start, the credit comes back straight away and the search answers failed with credit_refunded: true.

Send an Idempotency-Key: a retry with the same key answers the first search and never spends twice.

A test key answers a queued search that is stored nowhere and never runs. It spends nothing.

Scope: finder:write

post/v1/finder/searches

Request

  • Base URL: https://api.affiliaterail.com
  • URL: https://api.affiliaterail.com/v1/finder/searches
  • Auth: HTTP bearer

Request body

brand_idstring

Which brand. Defaults to the organization's oldest.

type'topic' | 'competitor' | 'lookalike' required

topic: who writes about a subject. competitor: who promotes a competitor. lookalike: YouTube channels like one you name.

seedstring required

The topic (3 to 80 characters), the competitor's domain or YouTube handle, or a YouTube channel, handle or video link

countrystring

ISO 3166-1 alpha-2. Required for topic.

Example request

{
  "brand_id": "fbr_7uSyy9FqVLCFWrdPeZaK"
}

Response

The search

idstring required

Prefixed id (fsc_…)

object'finder_search' required
brand_idstring required

Prefixed id (fbr_…)

type'topic' | 'competitor' | 'lookalike' | 'clone' required
seedstring required

What was searched: the topic, the competitor's domain or handle, the YouTube channel, or for clone the creators it started from

countrystring nullable required

Topic and clone searches only

labelstring required

What the app calls it in Recent searches

state'queued' | 'running' | 'done' | 'failed' | 'stopped_at_ceiling' required
foundinteger required
errorstring nullable required
credit_refundedboolean required

True when the search failed and its credit came back

created_atstring date-time required

ISO-8601, UTC

finished_atstring date-time nullable required

ISO-8601, UTC

livemodeboolean required

Example response

{
  "id": "fsc_7uSyy9FqVLCFWrdPeZaK",
  "brand_id": "fbr_7uSyy9FqVLCFWrdPeZaK",
  "created_at": "2026-08-21T10:15:30.000Z",
  "finished_at": "2026-08-21T10:15:30.000Z"
}

Changes

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