---
title: "Get Proxy Targeting"
method: GET
path: "/api/v1/proxy/targeting"
tags: ["proxy"]
---

# Get Proxy Targeting

`GET /api/v1/proxy/targeting`

## Request

- Base URL: `https://app.kaminari.ad`
- URL: `https://app.kaminari.ad/api/v1/proxy/targeting`
- Auth: HTTP bearer

Return the values accepted in a scan's `proxy` block for one country.

Every value listed here is accepted by `POST /api/v1/scans`, in any
case. That guarantee is about validation only: the provider's pool
moves continuously, so a scan may still fail to find an exit node at
crawl time.

An unsupported or unknown country returns 200 with empty arrays
rather than 404 — the useful answer to "can I target here" is a list,
possibly an empty one.

## Query parameters

- `country_code` string, required: ISO 3166-1 alpha-2 country code. Case-insensitive.
- `proxy_type` 'residential' | 'mobile': Which network to describe. Required in practice: the residential and mobile catalogues differ substantially, so values taken from one may be rejected for the other.
- `region` string: Narrow `cities` to one region. Omit for the country-wide city list. Pass a value from this endpoint's own `regions` array.

## Response `200`

Successful Response

- ProxyTargetingResponse: Values accepted in a scan's ``proxy`` block for one country.
  - `country_code` string, required: ISO 3166-1 alpha-2 code, upper-case.
  - `proxy_type` string, required: Network these values belong to. The catalogues differ substantially between residential and mobile, so a value listed for one is not necessarily accepted for the other.
  - `regions` string[], required: Accepted values for `proxy.region`, ordered by pool size (largest first).
  - `cities` string[], required: Accepted values for `proxy.city`, ordered by pool size. Narrowed to the `region` query parameter when one is given; otherwise the country-wide list, which is what to pick from when targeting by country alone. Pairing a region with a city from a different region yields no exit node.
  - `isps` string[], required: Accepted values for `proxy.isp`, ordered by pool size. Mobile carriers when `proxy_type=mobile`.
  - `refreshed_at` string, date-time, nullable, required: When these lists were last verified against the upstream provider, or null if we have not synced this country yet. Null means 'not looked yet', which is different from empty lists with a timestamp, which means 'no targeting available here'. This moves on every sync whether or not the contents changed — use the ETag header to detect actual changes.
  - `ttl_seconds` integer, required: How long these lists may be cached before we re-verify them upstream. Send the ETag back as If-None-Match to revalidate cheaply.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kaminari/apis/kaminari-ad-api.md) · [All operations](https://skmtc.dev/kaminari/apis/kaminari-ad-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaminari/apis/kaminari-ad-api/revisions/013f86e2fd32?raw)