curl -X GET "https://api.affonso.io/v1/finder/searches?limit=10&status=completed" \
-H "Authorization: Bearer sk_live_your_api_key"
{
"success": true,
"data": [
{
"id": "cmk2q1wau0001sb01lpvka001",
"name": "Creator tools",
"status": "completed",
"search_type": "topic",
"channel": "youtube",
"location": "2840",
"language": "en",
"exclude_domains": [],
"credits_used": 1,
"total_search_terms": 1,
"completed_search_terms": 1,
"total_results": 12,
"created_at": "2026-08-28T00:00:00.000Z",
"updated_at": "2026-08-28T01:00:00.000Z",
"completed_at": "2026-08-28T01:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1,
"has_next_page": false,
"has_prev_page": false
}
}
Affiliate Finder
List Finder Searches
List Affiliate Finder searches with status, progress, and credit usage
GET
/
v1
/
finder
/
searches
curl -X GET "https://api.affonso.io/v1/finder/searches?limit=10&status=completed" \
-H "Authorization: Bearer sk_live_your_api_key"
{
"success": true,
"data": [
{
"id": "cmk2q1wau0001sb01lpvka001",
"name": "Creator tools",
"status": "completed",
"search_type": "topic",
"channel": "youtube",
"location": "2840",
"language": "en",
"exclude_domains": [],
"credits_used": 1,
"total_search_terms": 1,
"completed_search_terms": 1,
"total_results": 12,
"created_at": "2026-08-28T00:00:00.000Z",
"updated_at": "2026-08-28T01:00:00.000Z",
"completed_at": "2026-08-28T01:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1,
"has_next_page": false,
"has_prev_page": false
}
}
Query Parameters
integer
default:"1"
Page number for pagination. Must be a positive integer.
integer
default:"50"
Number of results per page. Maximum value is 200. Default is 50.
string
Filter by processing status. Valid values:
pending, queued, running, analyzing, completed, failed, paused, reviewing.Response
The response includes a paginated list of Finder searches and pagination metadata.boolean
Always
true for successful responsesarray
Array of Finder search objects. Each object has the same structure as the Start Finder Search response.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the search
string
Search name
string
Current processing status, lowercase
string | null
topic or competitorstring | 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
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
nullobject
Pagination metadata object containing:
page(integer): Current page numberlimit(integer): Number of results per pagetotal(integer): Total number of searches matching the filtertotal_pages(integer): Total number of pageshas_next_page(boolean): Whether there is a next pagehas_prev_page(boolean): Whether there is a previous page
curl -X GET "https://api.affonso.io/v1/finder/searches?limit=10&status=completed" \
-H "Authorization: Bearer sk_live_your_api_key"
{
"success": true,
"data": [
{
"id": "cmk2q1wau0001sb01lpvka001",
"name": "Creator tools",
"status": "completed",
"search_type": "topic",
"channel": "youtube",
"location": "2840",
"language": "en",
"exclude_domains": [],
"credits_used": 1,
"total_search_terms": 1,
"completed_search_terms": 1,
"total_results": 12,
"created_at": "2026-08-28T00:00:00.000Z",
"updated_at": "2026-08-28T01:00:00.000Z",
"completed_at": "2026-08-28T01:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1,
"has_next_page": false,
"has_prev_page": false
}
}
Errors
| Status | Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | Invalid query parameters |
Notes
- Requires the
read:finderpermission. - Completed public searches with zero results are refunded automatically when they are listed. Searches whose results were later shortlisted are not refunded.
Was this page helpful?