Search role changes - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

This is a paid role-change unlock request with provider-supported filters, not free-form semantic search. Position values are constrained (for example ceo, cto, cfo, coo, founder, vp of sales, head of product); invalid values are rejected. The result includes the effective pricing rule and credits used.

Use the response pricing_rule and credits_used; charges depend on the active source pricing configuration.

The common response envelope contains items, total_found, billable_results, credits_used, pricing_rule, and metadata. Result item fields depend on this search family.

Body parameters

positionsrequired
array<string>
Required 1–16 values: ceo, cto, cfo, coo, vp of engineering, vp of sales, vp of marketing, head of product, head of growth, head of engineering, engineering manager, product manager, sales manager, marketing manager, founder, co-founder.
countries · optional
array<string>
Optional up to 25 uppercase two-letter country codes or supported region groups CEE, NORDICS, or LATAM.
date_preset · optional
string
Default: last_7d. Allowed: today, yesterday, last_7d, last_14d, last_30d, last_60d, last_90d, last_6m, last_1y, last_2y, this_week, this_month, this_quarter, this_year, last_week, last_month, last_quarter, last_year.
limit · optional
integer
Maximum records to unlock; default 5, range 1–5.

Name	Type	Description
positionsrequired	array<string>	Required 1–16 values: ceo, cto, cfo, coo, vp of engineering, vp of sales, vp of marketing, head of product, head of growth, head of engineering, engineering manager, product manager, sales manager, marketing manager, founder, co-founder.
countries	array<string>	Optional up to 25 uppercase two-letter country codes or supported region groups CEE, NORDICS, or LATAM.
date_preset	string	Default: last_7d. Allowed: today, yesterday, last_7d, last_14d, last_30d, last_60d, last_90d, last_6m, last_1y, last_2y, this_week, this_month, this_quarter, this_year, last_week, last_month, last_quarter, last_year.
limit	integer	Maximum records to unlock; default 5, range 1–5.

Errors

Status	Meaning
400	The search command or provider rejected the request.
401	Authentication is required.
402	Insufficient credits for this search.
403	Developer API key lacks required scope: search:run.
422	A request field is missing, outside its allowed range, or fails the typed request contract.

Example

bash

curl -X POST "https://app.autotouch.ai/api/search/role-changes" -H "Authorization: Bearer $AUTOTOUCH_API_KEY" -H "Content-Type: application/json" -d '{"positions":["cto","vp of engineering"],"countries":["US"],"date_preset":"last_30d","limit":5}'

Request body

json

{
  "positions": [
    "cto",
    "vp of engineering"
  ],
  "countries": [
    "US"
  ],
  "date_preset": "last_30d",
  "limit": 5
}

Response example

json

{
  "items": [],
  "total_found": 0,
  "billable_results": 0,
  "credits_used": 0,
  "pricing_rule": "<effective rule for this search>",
  "metadata": {}
}