List 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
  }
}

GET

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 responses

array

Array of Finder search objects. Each object has the same structure as the Start Finder Search response.

Show Data Object Properties

string

Unique identifier for the search

string

Search name

string

Current processing status, lowercase

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

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

object

Pagination metadata object containing:

page (integer): Current page number
limit (integer): Number of results per page
total (integer): Total number of searches matching the filter
total_pages (integer): Total number of pages
has_next_page (boolean): Whether there is a next page
has_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:finder permission.
Completed public searches with zero results are refunded automatically when they are listed. Searches whose results were later shortlisted are not refunded.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Query Parameters

Response

Errors

Notes

​Query Parameters

​Response

​Errors

​Notes

Query Parameters

Response

Errors

Notes