Start Finder Search

curl -X POST "https://api.affonso.io/v1/finder/searches" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Creator tools",
    "search_type": "topic",
    "search_terms": ["affiliate marketing"],
    "channel": "youtube",
    "location": "2840",
    "language": "en",
    "exclude_domains": []
  }'

{
  "success": true,
  "data": {
    "id": "cmk2q1wau0001sb01lpvka001",
    "name": "Creator tools",
    "status": "pending",
    "search_type": "topic",
    "channel": "youtube",
    "location": "2840",
    "language": "en",
    "exclude_domains": [],
    "credits_used": 1,
    "total_search_terms": 0,
    "completed_search_terms": 0,
    "total_results": 0,
    "created_at": "2026-08-28T00:00:00.000Z",
    "updated_at": "2026-08-28T00:00:00.000Z",
    "completed_at": null
  }
}

POST

finder

searches

curl -X POST "https://api.affonso.io/v1/finder/searches" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Creator tools",
    "search_type": "topic",
    "search_terms": ["affiliate marketing"],
    "channel": "youtube",
    "location": "2840",
    "language": "en",
    "exclude_domains": []
  }'

{
  "success": true,
  "data": {
    "id": "cmk2q1wau0001sb01lpvka001",
    "name": "Creator tools",
    "status": "pending",
    "search_type": "topic",
    "channel": "youtube",
    "location": "2840",
    "language": "en",
    "exclude_domains": [],
    "credits_used": 1,
    "total_search_terms": 0,
    "completed_search_terms": 0,
    "total_results": 0,
    "created_at": "2026-08-28T00:00:00.000Z",
    "updated_at": "2026-08-28T00:00:00.000Z",
    "completed_at": null
  }
}

Each unique search term consumes one discovery credit for the selected channel. Failed starts and completed public searches with zero results are refunded automatically. Searches whose results were later shortlisted are not refunded.

Body Parameters

string

required

Search name. Must be between 1 and 120 characters.

string

required

How search terms are interpreted. Valid values: topic, competitor.

string[]

required

Topic queries or competitor names. Minimum 1 term, maximum 50. Each term must be between 1 and 200 characters. Duplicate terms are searched and charged only once.

string

required

Channel to search. Valid values: websites, youtube, reddit, instagram, tiktok, linkedin, facebook, x, medium, substack.

string

default:"2840"

Location code as a digit string. Default 2840 is the United States.

string

default:"en"

Two-letter language code. Default en.

string[]

default:"[]"

Domains to exclude. Maximum 100 items. Each domain is at most 253 characters. Defaults to an empty list.

Response

The response includes the created Finder search. Processing continues asynchronously.

boolean

Always true for successful responses

object

The created Finder search object.

Show Data Object Properties

string

Unique identifier for the search

string

Search name

string

Current processing status, lowercase. Newly created searches start as pending. Other values: queued, running, analyzing, completed, failed, paused, reviewing.

string | null

topic or competitor

string | null

Channel used for the search

string

Location code used for the search

string

Two-letter language code used for the search

string[]

Domains excluded from the search

integer

Discovery credits charged for unique search terms

integer

Progress total for search terms. Starts at 0 until the processor updates it.

integer

Search terms that have finished processing

integer

Number of discovered results

string

ISO 8601 timestamp of when the search was created

string

ISO 8601 timestamp of when the search was last updated

string | null

ISO 8601 timestamp of when the search completed, otherwise null

curl -X POST "https://api.affonso.io/v1/finder/searches" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Creator tools",
    "search_type": "topic",
    "search_terms": ["affiliate marketing"],
    "channel": "youtube",
    "location": "2840",
    "language": "en",
    "exclude_domains": []
  }'

{
  "success": true,
  "data": {
    "id": "cmk2q1wau0001sb01lpvka001",
    "name": "Creator tools",
    "status": "pending",
    "search_type": "topic",
    "channel": "youtube",
    "location": "2840",
    "language": "en",
    "exclude_domains": [],
    "credits_used": 1,
    "total_search_terms": 0,
    "completed_search_terms": 0,
    "total_results": 0,
    "created_at": "2026-08-28T00:00:00.000Z",
    "updated_at": "2026-08-28T00:00:00.000Z",
    "completed_at": null
  }
}

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid request body
`403`	`INSUFFICIENT_CREDITS`	Not enough discovery credits for the unique search terms
`404`	`NOT_FOUND`	No affiliate program found for the API key’s team
`503`	`PROCESSING_UNAVAILABLE`	The search could not be started and no discovery credits were consumed

Notes

Requires the write:finder permission.
Use GET /v1/finder/searches to poll status, then GET /v1/finder/searches/{id}/results to read discovered opportunities.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Response

Errors

Notes

​Body Parameters

​Response

​Errors

​Notes

Body Parameters

Response

Errors

Notes