Every capture runs in a specific region. The AI apps we capture from tailor their answers to where the request appears to come from — so a query about “best running shoes” returns different sources, shopping cards, and citations in the US than it does in Germany or Japan. The regions array lets you target that geography precisely.

​
The regions array

regions is an array of region objects. Each object describes one place to capture from. The default, when you omit regions entirely, is a single US capture: 
"regions": [{ "country": "US" }]
​
country
string
required
ISO-3166 alpha-2 country code (e.g. US, GB, DE, JP). Case-insensitive. This is the only required field in a region object.
​
city
string
Optional city name to narrow targeting within the country (e.g. London, San Francisco). Useful for locale-sensitive queries like local businesses or regional pricing.
​
language
string
Optional language hint for the capture (e.g. en, de, ja). When omitted, the surface uses its own default for the country.

​
One child per surface × region

The most important rule: the API creates one child job for every combination of surface and region. Surfaces and regions multiply. If you request two surfaces across two regions, you get four children: 
curl -X POST https://api.aisearchapi.dev/v1/search \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best noise-cancelling headphones",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [
      { "country": "US" },
      { "country": "GB", "city": "London", "language": "en" }
    ]
  }'
The parent response is a 202 with one child id per pairing: 
{
  "jobId": "job_8t2q",
  "status": "processing",
  "children": [
    "job_8t2q.chatgpt.us",
    "job_8t2q.chatgpt.gb",
    "job_8t2q.perplexity.us",
    "job_8t2q.perplexity.gb"
  ]
}
Child ids encode the surface and region: job_<id>.<surface>.<region>. Fetch any child with GET /v1/jobs/:id to receive its Envelope, or poll the parent for the rollup. See Asynchronous jobs for the full polling flow.
Each capture is billed separately. surfaces × regions is exactly how many captures you pay for. Two surfaces across two regions is four captures, not two. See Credits & pricing before fanning out across many regions.

​
Requested vs. effective region

We always try to honor the exact region you asked for. When a surface can’t be captured from precisely that location, we capture from the closest workable location instead and tell you — rather than silently returning something from the wrong place. Every Envelope reports both values under provenance.region:
​
provenance.region.requested
object
The region object exactly as you specified it in the request.
​
provenance.region.effective
object
The region the capture actually ran from. When it matches requested, the region was honored exactly. When it differs, the surface answered from effective instead.
For a capture that was honored exactly: 
{
  "provenance": {
    "region": {
      "requested": { "country": "GB", "city": "London", "language": "en" },
      "effective": { "country": "GB", "city": "London", "language": "en" }
    }
  }
}
When only the city could not be honored, effective falls back to the broader region: 
{
  "provenance": {
    "region": {
      "requested": { "country": "GB", "city": "Inverness", "language": "en" },
      "effective": { "country": "GB", "language": "en" }
    }
  }
}
Always read provenance.region.effective — not your original request — when you attribute a result to a geography. Comparing the two fields tells you whether a locale-sensitive answer can be trusted at city precision.

​
Choosing regions

List one region object per market you care about. Because every surface runs in every region, you get a clean matrix — the same parser handles job_<id>.chatgpt.us and job_<id>.chatgpt.de identically.
Add the language field to capture the same country in different languages (e.g. { "country": "CH", "language": "de" } and { "country": "CH", "language": "fr" }). Each is a separate capture and a separate child.
For queries with strong local intent — nearby businesses, regional availability, local pricing — set city. If the city can’t be honored, effective shows you the fallback so you know the precision you actually got.

​
Next steps

Credits & pricing

See how regions multiply captures and what each surface costs.

Search API reference

Full request and response schema for POST /v1/search.