# Référence des endpoints API

> URL: https://foura.ai/fr/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Une référence pour tous les endpoints de l'API FourA avec les paramètres de request et les formats de response.

## Base URL

```
https://eu.api.foura.ai/api
```

## Authentification

Chaque request requiert votre clé API dans le header `X-API-Key` :

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'
```

Créez et gérez vos clés API dans le [Dashboard](https://foura.ai/dashboard). Les clés utilisent le préfixe `pk_live_`.

## Headers de réponse

Les réponses de `/api/*` comportent deux headers de corrélation :

| Header | Valeur | Description |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | ID unique attribué à la requête. Renvoyé sur chaque réponse, y compris 4xx et 5xx, sauf si le corps ne peut pas être lu par FourA : `400 Invalid JSON in request body` et `413` sont refusés avant l'attribution d'un ID. Enregistrez-le de votre côté. |
| `X-FourA-Credits` | integer | Crédits consommés pour cette requête. Renvoyé sur chaque réponse ayant atteint un moteur, qu'elle soit un succès ou un échec (le travail a été effectué dans les deux cas). Un appel refusé par FourA avant l'exécution d'un moteur (clé manquante ou invalide, limite de plan ou de plateforme, cible ou ID de proxy refusé) n'en comporte aucun. Consultez [Résultats des requêtes](https://foura.ai/docs/api/outcomes) pour connaître les résultats facturables. |

Le même ID de requête sert de clé pour l'aperçu des charges utiles de requête et de réponse dans l'[Activity Log](https://foura.ai/docs/dashboard/activity-log) du Dashboard (conservé 24 heures, les 200 dernières par clé), afin que vous puissiez retrouver la requête exacte plus tard et la rejouer depuis Activity directement dans le [Playground](https://foura.ai/docs/dashboard/playground). Indiquez-le lorsque vous contactez le support pour identifier la requête en quelques secondes.

```bash
$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...
```

Consultez [Response Headers](https://foura.ai/docs/api/response-headers) pour la liste complète et les conseils d'utilisation.

## Endpoints

> **Vous utilisez ces endpoints via MCP ?** Le serveur [`@fouradata/mcp`](https://foura.ai/docs/mcp/server) encapsule les quatre endpoints sous forme d'outils MCP natifs (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) avec les mêmes formats d'entrée, plus une option `offload_large` pour une gestion optimisée des réponses volumineuses en termes de tokens. Les différences : `foura_browser` n'a pas de champ `lean`, et `foura_proxy` ne prend pas encore en charge les champs de [localisation de sortie](#exit-location).

FourA propose quatre endpoints de request, chacun optimisé pour un cas d'usage différent :

| Endpoint | Idéal pour |
|----------|----------|
| `POST /auto/` | Récupération intelligente. Vous transmettez une URL, FourA choisit la méthode la plus économique et efficace (proxy tournant ou navigateur, complété par une request directe avec `forceProxy: false`) et mémorise ce qui fonctionne par hôte. |
| `POST /single/` | Requests HTTP rapides, pages statiques, API |
| `POST /proxy/` | Sites protégés avec rotation automatique de proxy, ciblage géographique visible par la cible en option |
| `POST /browser/` | Pages avec rendu JavaScript, SPA |
| `GET /profiles` | Le catalogue de profils de navigateur pour `single` et `proxy`. Public, sans clé API. |

Pour une analyse détaillée afin de choisir la solution adaptée, consultez [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type) et le [guide Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Restrictions sur les URL cibles

Les cibles qui pointent vers des plages d'IP privées, de bouclage ou réservées (RFC 5735, RFC 6598, plages réservées IPv6) sont rejetées avec une erreur 400 avant que la request ne quitte FourA. Seuls les noms d'hôtes et les IP publics sont transmis.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Une cible située sur l'hôte API propre à FourA (`eu.api.foura.ai` ou `api.foura.ai`) est également refusée avec un code 400, sur l'ensemble des quatre endpoints, avant que quoi que ce soit ne soit récupéré ou facturé. Une URL contenant un espace ou un caractère de contrôle est refusée avec un code 400 de la même manière sur Single, Proxy et Auto; encodez l'espace sous la forme `%20` (Browser le récupère comme le fait Chrome). La seule page que FourA récupère dans ce cadre est [`/inspect`](https://foura.ai/docs/api/inspect).

```json
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
```

---

## Smart Fetch (Auto)

`POST /api/auto/`

Vous transmettez une URL ainsi que des regles `validate` facultatives. FourA parcourt une hierarchie optimisee selon les couts (proxy avec rotation, puis navigateur complet) et s'arrete au premier echelon qui renvoie une response acceptee par vos regles. Avec `forceProxy: false`, une sonde directe peu couteuse est executee en premier. Lors des appels repetes vers le meme hote, une session active est rejouee a la place, ce qui rend le deuxieme appel peu couteux.

Vous n'avez pas a regler les tentatives de retry, la taille des pools ou le nombre de proxys. FourA les apprend pour chaque hote.

### Request Body

| Parametre | Type | Requis | Par defaut | Description |
|-----------|------|----------|---------|-------------|
| `url` | string | Oui | - | URL cible |
| `method` | string | Non | `"GET"` | Methode HTTP |
| `headers` | [string, string][] | Non | - | Headers a envoyer a la cible, sous forme de paires [nom, valeur]. Chaque echelon les envoie sauf l'echelon de type navigateur. Un `Cookie` envoye atteint le site sans modification, et les cookies d'une session enregistree ne sont ajoutes a cote que sous des noms que vous n'avez pas envoyes. Le `userAgent` d'une session enregistree remplace votre `User-Agent`. L'echelon proxy omet les headers conditionnels tels que `If-None-Match`, sauf si votre `validate.status.accept` inclut `304`. |
| `data` | any | Non | - | Request body pour les requests differentes de GET |
| `validate` | object | Non | - | Criteres de succes, meme format que le champ `validate` de Single Request (voir ci-dessous). Indiquez au mode auto a quoi ressemble une vraie page afin qu'il distingue le contenu reel d'une page de challenge. |
| `returnSession` | boolean | Non | `true` | Inclure la session retenue (`proxy`, `cookies`, `userAgent`) dans la response pour vous permettre de la rejouer via `/api/single/` ou `/api/browser/`. |
| `forceProxy` | boolean | Non | `true` | Toujours router via un proxy avec rotation. Definissez `false` pour autoriser le chemin direct plus economique quand la cible le permet (certaines defenses sont plus strictes face au trafic issu de proxys). |
| `timeout_ms` | integer | Non | `120000` | Budget temporel total pour l'ensemble de l'appel, en millisecondes. Toutes les sous-tentatives s'executent dans la limite de ce budget. Min `5000`, max `180000`. |
| `ignoreProxies` | string[] | Non | - | Identifiants de proxy a eviter lors de chaque sous-tentative. Utilisez les identifiants retournes par de precedentes responses `/api/auto/` ou `/api/proxy/`. |
| `followRedirects` | integer | Non | `5` | Nombre maximal de redirections a suivre sur les echelons economiques de la hierarchie. `0` pour desactiver. Max `20`. |
| `exitClass` | string | Non | - | `standard` ou `premium`, comme sur [Proxy Request](#exitclass). `premium` permet a l'appel de basculer vers une sortie premium des lors que le pool standard ne parvient pas a joindre la page. Necessite un forfait incluant les sorties premium. Consultez [exitClass on Smart Fetch](#exitclass-on-smart-fetch). |

### Response

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `status` | number | Statut HTTP renvoyé par la cible. |
| `data` | string | Corps de la réponse sous forme de texte, quel que soit l'échelon qui l'a servi. Une page JSON est renvoyée sous forme de texte JSON, vous devez donc l'analyser vous-même. |
| `headers` | array or object | En-têtes de réponse de la cible. Les échelons Single et proxy renvoient un tableau d'objets d'en-têtes par saut (per-hop); les échelons browser renvoient un objet plat. |
| `meta.rung` | string | Échelon de l'échelle qui a livré la réponse. L'un des suivants: `probe` (requête directe économique, uniquement avec `forceProxy: false`), `proxy` (proxy tournant), `browser` (rendu complet par navigateur), `cache` (session chaude rejouée), `warmup` (la page d'entrée du site a été récupérée d'abord et ses cookies ont ouvert l'URL profonde), ou `fail` (aucun échelon n'a produit de réponse acceptée). |
| `meta.solved` | boolean | Indique si la page nécessitait une étape supplémentaire (une page de vérification ou challenge) et si celle-ci a été complétée durant cet appel. |
| `meta.attempts` | number | Sous-tentatives effectuées avant le succès. |
| `meta.credits` | number | Total des crédits consommés pour cet appel. Correspond à `X-FourA-Credits`. |
| `meta.attemptsByEngine` | object | Requêtes envoyées à `single`, `proxy` et `browser`. Une requête de navigateur refusée par votre forfait est comptabilisée, car elle a été envoyée. |
| `meta.browserRequests` | number | Requêtes de navigateur ayant consommé un créneau de votre quota quotidien. Une requête de navigateur refusée par votre forfait ne consomme rien. |
| `meta.exitClass` | string | Classe de sortie ayant livré la réponse, présente lorsque la requête précisait un `exitClass`: `premium` ou `standard`. La même valeur est transmise dans le header de réponse `X-FourA-Exit-Class`. |
| `session.proxy` | string | Identifiant encodé du proxy ayant livré la réponse. Réutilisez-le sur une requête Single ou Browser. Présent lorsque `returnSession` vaut `true`. |
| `session.cookies` | array | Cookies à rejouer, chacun comportant au minimum `name` et `value`. Un échelon browser renvoie le cookie jar du navigateur. Un échelon proxy, ou la sonde directe, ne renvoie que les cookies qui ont débloqué la page (comme ceux définis par la page de vérification d'un site), jamais l'ensemble des cookies définis par la page, la liste peut donc être vide. Présent lorsque `returnSession` vaut `true`. |
| `session.userAgent` | string | User-Agent utilisé lors de la tentative réussie. Présent lorsque `returnSession` vaut `true`. |
| `error` | string | Message d'erreur en cas d'échec de l'appel. |
| `attemptReport` | object | En cas d'échec de l'appel: les requêtes du moteur revenues sans la page, ventilées par cause. Voir [Smart Fetch](https://foura.ai/docs/guides/smart-fetch). |

### Exemple

```bash
curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'
```

### Remarques

- Auto est un coordinateur. Il appelle Single, Proxy ou Browser en interne et transmet votre clé API à chaque sous-appel. L'appel Auto représente une seule requête dans votre [Activity Log](https://foura.ai/docs/dashboard/activity-log) et sur votre Overview, avec la somme des crédits de ses sous-appels ; les sous-appels sont listés sous celui-ci en tant que tentatives, et ils ne comptent jamais comme des requêtes à part entière.
- Passez `validate.data.accept` avec une sous-chaîne que seule la vraie page contient. Sans cela, Auto ne peut pas distinguer un vrai 200 d'un interstitiel de challenge renvoyé avec le statut 200.
- Une page supprimée est la réponse du site, pas un refus. Lorsque deux sorties renvoient le même `404` ou `410` et que votre `validate` ne l'accepte pas, l'appel se termine avec ce `status` et un `error` qui commence par `the site answered`. Listez le statut dans `validate.status.accept` et Auto renvoie la première réponse avec ce statut qui valide le reste de vos `validate`. Il en va de même pour tout autre statut que vous y listez, sauf `403`, `429`, `503` et `202`, que les sites envoient également avec une page de challenge.
- `timeout_ms` plafonne l'ensemble de l'appel. Un premier accès à froid à un site protégé peut prendre plusieurs dizaines de secondes ; les sessions réutilisées à chaud se terminent généralement en moins d'une seconde.

### exitClass sur Smart Fetch

`exitClass` fonctionne sur Smart Fetch de la même façon que sur [Proxy Request](#exitclass) : c'est une autorisation, pas une instruction. Auto tente d'abord le pool standard. Lorsque le pool standard ne peut pas atteindre la page et que la requête spécifie `premium`, Auto ouvre la page dans un navigateur via une sortie premium. La session qu'il y construit sert vos appels ultérieurs vers le même site qui spécifient aussi `premium` ; les appels qui ne le spécifient pas ne l'utilisent jamais.

L'épuisement du quota n'est pas une erreur. Une fois le trafic premium de votre forfait consommé pour la période de facturation, l'appel se poursuit dans le pool standard et `meta.exitClass` indique `standard`. Sur un forfait sans sorties premium, un appel qui envoie `exitClass: premium` est refusé avec un `403` portant `X-FourA-Limit: plan_limit_premium`, avant tout traitement.

Le trafic premium est mesuré comme sur Proxy Request. Une page ouverte dans un navigateur charge plus d'éléments que la page elle-même, donc une page Smart Fetch premium consomme plus de trafic premium que la même page récupérée par Proxy Request. Pour limiter cette consommation, une page Smart Fetch premium se charge sans images, polices ni médias, et sans scripts provenant de fournisseurs de publicité, d'analyse et de consentement connus.

---

## Single Request

`POST /api/single/`

Envoie une requête HTTP avec des caractéristiques réseau réalistes similaires à celles d'un navigateur, sans lancer de véritable navigateur. C'est le endpoint le plus rapide.

### Request Body

| Paramètre | Type | Requis | Par défaut | Description |
|-----------|------|----------|---------|-------------|
| `method` | string | Oui | - | Méthode HTTP : GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | Oui | - | URL cible. Utilisez `{ts}` n'importe où dans l'URL pour insérer le timestamp actuel afin d'éviter le cache. |
| `headers` | [string, string][] | Non | - | Headers personnalisés sous forme de paires [nom, valeur] |
| `unblocker` | boolean | Non | `true` | Envoyer des headers de navigateur réalistes (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Activé par défaut. Définissez `false` et FourA n'ajoute aucun header de navigateur, uniquement ceux que vous transmettez. |
| `timeout_ms` | number | Non | 15000 | Timeout global en ms (max : 120000) |
| `connect_timeout_ms` | number | Non | 5000 | Timeout de connexion en ms |
| `accept_timeout_ms` | number | Non | 5000 | Timeout d'acceptation en ms (temps d'attente pour l'acceptation de la connexion) |
| `server_response_timeout_ms` | number | Non | 15000 | Timeout de réponse du serveur en ms (temps d'attente pour le premier octet) |
| `dns_cache_timeout_sec` | number | Non | 120 | TTL du cache DNS en secondes (max : 240) |
| `followRedirects` | number | Non | disabled | Nombre maximal de redirections à suivre (0-20). Omettez pour désactiver. |
| `tryJsonData` | boolean | Non | false | Parser le corps de la réponse en JSON si possible |
| `returnBuffer` | boolean | Non | false | Retourner un buffer brut au lieu d'une chaîne décodée |
| `data` | any | Non | - | Corps de la requête (string ou object, auto-sérialisé en JSON) |
| `proxy` | string | Non | - | ID de proxy issu d'une réponse précédente, pour conserver la même sortie. Renvoyez la chaîne opaque telle quelle. Une adresse de proxy brute est rejetée avec `400 Invalid proxy format`. Certains ID ne peuvent pas être épinglés : voir [Pinning an exit](#pinning-an-exit). |
| `browser` | string | Non | Chrome | Navigateur à présenter : Chrome, Edge, Safari, Firefox ou Tor. Voir [Browser profiles](#browser-profiles). |
| `os` | string | Non | - | Système d'exploitation à présenter : Windows, macOS, Android ou iOS. Un nom de famille accepte n'importe laquelle de ses versions. |
| `version` | string | Non | newest | Version du navigateur à présenter, telle qu'indiquée dans le catalogue. La correspondance la plus récente l'emporte lorsque plusieurs conviennent. |
| `profile` | string | Non | - | Identifiant exact du profil issu de `GET /api/profiles`, à la place des trois champs ci-dessus. |
| `validate` | object | Non | - | Règles de validation de la réponse (voir ci-dessous) |

### Profils de navigateur

Par défaut, une requête présente la dernière version de Google Chrome. Certaines cibles acceptent un navigateur et en refusent un autre ; ainsi, `browser`, `os` et `version` permettent de filtrer un catalogue de profils mesurés, et `profile` en sélectionne un par son identifiant.

```json
{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}
```

Règles :

- La sélection nécessite `unblocker` (activé par défaut). Avec `unblocker` désactivé, aucun header de navigateur n'est envoyé, la request est donc refusée plutôt qu'appliquée partiellement.
- Lorsque plusieurs profils correspondent, la version la plus récente est retenue.
- Une combinaison que le catalogue ne peut pas fournir renvoie une erreur indiquant ce qui est disponible, et un identifiant `profile` inconnu renvoie `unknown profile '<id>'`. La request n'est jamais envoyée sous l'identité d'un autre navigateur.
- Les quatre mêmes champs sont disponibles dans l'objet `request` de `POST /proxy/`.

`GET /api/profiles` renvoie l'intégralité du catalogue et ne nécessite aucune clé API :

```json
{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}
```

`osFamily` est la valeur sur laquelle filtrer lors de la création d'un sélecteur; `os` conserve le nom de la version pour l'affichage.

### Règles de validation

L'objet `validate` vous permet de définir les conditions de succès et d'échec. Si une condition `fail` correspond, la requête est traitée comme un échec. Si des conditions `accept` sont définies, seules les réponses correspondantes sont traitées comme un succès.

```json
{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `validate.status.accept` | number[] | Codes d'état HTTP à accepter |
| `validate.status.fail` | number[] | Codes d'état HTTP à rejeter |
| `validate.headers.accept` | object | La response est acceptée si au moins une paire correspond lors d'un saut de redirection. Les noms et les valeurs correspondent sans distinction de casse, sur une partie du texte. |
| `validate.headers.fail` | object | Paires clé-valeur d'en-tête déclenchant un échec |
| `validate.data.accept` | string[] | La response est acceptée si le corps contient au moins une de ces chaînes |
| `validate.data.fail` | string[] | Chaînes dans le corps de la response déclenchant un échec |

### Exemple

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'
```

Response :

```json
{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}
```

Lorsque la cible effectue une vérification de bot avant d'accéder au corps, la response contient également un objet `defense` indiquant le fournisseur et si la vérification a été validée :

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `status` | number | Code d'état HTTP de la cible |
| `headers` | array | Un objet par saut de redirection. Chacun possède un champ `result` contenant la ligne de statut ainsi que chaque header de réponse. Les headers à valeurs multiples (`Set-Cookie`, `Link`, `WWW-Authenticate`) sont renvoyés sous forme de tableaux de chaînes. |
| `data` | string/object | Corps de la réponse (JSON si `tryJsonData` est vrai) |
| `total_time` | number | Durée totale de la requête en secondes |
| `proxy` | string | Identifiant encodé du proxy par lequel la requête a transité (uniquement si un `proxy` a été fourni dans la requête). Réutilisez-le lors d'un appel ultérieur pour conserver la même sortie. |
| `defense` | object | Présent lorsque la cible a exécuté une vérification de bot sur cette requête, ou lorsqu'une nouvelle tentative avec les propres cookies du site a généré le corps. `defense.solved` indique si une vérification a été passée, `defense.retry` indique si une nouvelle tentative vous a permis d'obtenir le contenu. Consultez [Vérifications du site](https://foura.ai/docs/api/site-checks) pour chaque champ et la liste complète des systèmes. |
| `error` | string | Message d'erreur si la requête a échoué |

---

## Requête Proxy

`POST /api/proxy/`

Achemine votre requête via des proxys tournants avec nouvelle tentative automatique en cas d'échec. Vous pouvez éventuellement restreindre la sélection à un ensemble de pays de sortie visibles par la cible.

### Corps de la requête

| Paramètre | Type | Requis | Valeur par défaut | Description |
|-----------|------|----------|---------|-------------|
| `request` | object | Oui | - | Un corps de requête unique (mêmes champs que Requête unique ci-dessus) |
| `timeout_ms` | number | Non | 45000 | Timeout global pour toutes les tentatives en ms (max : 120000) |
| `maxTries` | number | Non | 5 | FourA cesse de lancer de nouvelles tentatives lorsque ce nombre d'échecs est atteint (max : 90). Les tentatives s'exécutent en parallèle, le nombre total de tentatives terminées peut donc être légèrement supérieur. |
| `ignoreProxies` | string[] | Non | - | Identifiants de proxy à exclure de la rotation (utilisez les identifiants renvoyés par les réponses précédentes) |
| `exitCountries` | string[] | Non | - | Liste d'autorisation stricte de codes pays à deux lettres visibles par la cible (ex. `["CZ", "GB"]`). Les valeurs sont nettoyées des espaces, converties en majuscules et dédupliquées. Les sorties du pool standard avec un pays inconnu sont exclues, et le pool standard ne bascule jamais vers un pays non demandé. Une sortie premium part également de l'un des pays listés. |
| `exitClass` | string | Non | - | `standard` ou `premium`. `premium` permet à la requête de passer à une sortie premium lorsque le pool standard rencontre des difficultés sur une cible protégée. Nécessite un forfait incluant les sorties premium. |
| `exitState` | string | Non | - | Région d'où part la sortie. Nécessite `exitClass: premium` et exactement un pays dans `exitCountries`. Voir [Emplacement de sortie](#exit-location). |
| `exitCity` | string | Non | - | Ville d'où part la sortie. Nécessite `exitClass: premium` et exactement un pays dans `exitCountries`. |
| `exitAsn` | string | Non | - | Réseau d'où part la sortie, par numéro d'AS, par exemple `8866`. Nécessite `exitClass: premium` et exactement un pays dans `exitCountries`. |
| `exitOs` | string | Non | - | `windows`, `android`, `ios` ou `mac` : type d'appareil auquel appartient l'adresse. Nécessite `exitClass: premium`. |
| `exitLifetimeMin` | integer | Non | - | Durée en minutes pendant laquelle la sortie conserve son adresse, de `3` à `1440`. Nécessite `exitClass: premium`. |

### Portée de exitCountries

La sélection utilise les dernières métadonnées de pays visibles par la cible disponibles, généralement actualisées sous environ dix minutes. Il ne s'agit pas d'une recherche de géolocalisation en direct pendant la requête. Ne déduisez pas le pays de desserte à partir de l'adresse de l'hôte proxy.

Si le pool actuel ne contient aucune correspondance pour les pays demandés et que la requête n'a pas spécifié `exitClass: premium`, la réponse renvoie un code HTTP 200 avec une enveloppe d'erreur :

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

Conservez le périmètre demandé et réessayez plus tard. Modifiez-le ou élargissez-le uniquement si l'exigence de pays de votre workflow change explicitement.

### Exemple

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'
```

Response :

```json
{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `proxy` | string | Identifiant encode du proxy utilise. Reutilisez-le sur une requete Single ou Browser en le transmettant dans le champ `proxy`, ou ignorez-le lors de la prochaine requete Proxy via `ignoreProxies`. |
| `exitCountry` | string | Code pays a deux lettres visible par la cible pour le proxy ayant servi la requete. Present uniquement lorsque la requete a defini `exitCountries`, quelle que soit la classe de sortie utilisee. Verifiez toujours qu'il s'agit de l'un des codes demandes avant de faire confiance a la reponse. |
| `exitClass` | string | Classe de sortie ayant servi cette requete, presente sur une reponse reussie lorsque la requete en a specifie une. `premium` indique qu'une sortie premium a renvoye le corps; `standard` indique que le pool standard l'a fait. Un appel en echec n'a rien servi, il ne comporte donc pas de `exitClass`; consultez son `attemptReport` pour connaitre ce que les tentatives ont rencontre. |
| `total` | number | Duree reelle totale externe en secondes (flottant). Inclut la selection du proxy, les nouvelles tentatives et la tentative reussie. `total_time` concerne uniquement la requete interne; `total` est toujours >= `total_time`. |
| `profile` | string | Profil de navigateur choisi par la rotation, present **uniquement** s'il differe de celui demande. S'il est absent, la requete a ete executee exactement comme definie. Renvoyez l'identifiant via `profile` lors des appels suivants pour conserver le navigateur fonctionnel. |
| `error` | string | Message d'erreur en cas d'echec de la requete. En cas d'erreur de scope, `code` vaut `no_eligible_proxy` et `details.exitCountries` renvoie le scope normalise. |
| `attemptReport` | object | Present sur **chaque** appel Proxy en echec. Comptabilise ce que les tentatives ont rencontre, afin qu'un pool bloque, un pool inactif et une regle `validate` sans correspondance ne soient pas interpretes comme une seule et meme erreur. Voir ci-dessous. |
| `request` | object | Present sur un appel Proxy en echec : requete executee par FourA, avec les valeurs par defaut renseignees et vos `ignoreProxies` tels qu'envoyes. |

Tous les champs de reponse de Single Request sont egalement inclus, dont `defense` : une tentative de proxy confrontée a un controle anti-bot le signale de la meme maniere que Single.

### Pourquoi un appel Proxy a echoue

`Download maxTry limit reached` s'affiche de la meme maniere quel que soit le deroulement des tentatives, chaque reponse Proxy en echec inclut donc un `attemptReport` a cote de l'erreur :

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `total` | integer | Tentatives effectuées |
| `noResponse` | integer | La sortie n'a jamais répondu, le site n'a donc jamais été atteint |
| `defense` | integer | Le site a répondu et une vérification de bot a été identifiée sur cette réponse |
| `contentRejected` | integer | HTTP 200, aucune vérification de bot, rejeté uniquement par votre `validate.data` |
| `statusRejected` | integer | Le site a répondu, aucune vérification de bot, rejeté par votre `validate.status` |
| `other` | integer | A répondu, et aucun des cas ci-dessus |
| `vendors` | string[] | Fournisseurs de vérification de bot identifiés dans la tâche |
| `profilesTried` | string[] | Profils de navigateur envoyés par la tâche, par ordre de première utilisation. `default` indique que votre request est partie sans modification. |
| `summary` | string | Une phrase construite à partir des compteurs, prête pour vos logs |

La chaîne `error` reste inchangée, garantissant le fonctionnement continu d'un client qui effectue une correspondance dessus. Ce qu'il faut faire pour chaque compteur : [Pourquoi une requête de proxy a épuisé ses tentatives](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### exitClass

Certaines cibles refusent les sorties du pool standard quel que soit le nombre de tentatives. `exitClass: premium` indique à Proxy qu'il peut faire passer une telle request sur une **sortie premium** en plus du pool standard, plutôt que de simplement effectuer des rotations au sein de celui-ci.

```json
{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}
```

Trois points méritent d'être connus avant l'envoi.

**Il s'agit d'une autorisation, pas d'une instruction.** Le pool standard tente toujours de répondre en premier, et l'emporte généralement. Une sortie premium intervient uniquement lorsque le pool a consommé un court délai sur la request ou que la cible l'a visiblement refusée. Une request traitée par le pool standard avant toute tentative de sortie premium constitue un succès normal et ne vous coûte aucun trafic premium. Dès qu'une sortie premium a été tentée, son trafic est décompté, comme décrit ci-dessous.

**Une sortie premium reste dans `exitCountries`.** Avec une liste de pays, une sortie premium part de l'un de ces pays et `exitCountry` l'indique dans la response, comme pour le pool standard.

**La response vous indique ce qui vous a réellement servi.** Lorsque vous spécifiez une classe, la response renvoie `exitClass` :

```json
{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}
```

`premium` signifie qu'une sortie premium a renvoyé le corps. `standard` signifie que le pool standard l'a fait, ce qui correspond également à la réponse obtenue lorsqu'une sortie premium n'a pas pu être obtenue, et lorsque le trafic premium inclus dans votre forfait (plus les ajouts achetés) est épuisé pour la période de facturation. Aucun des deux n'est une erreur, et vous pouvez rapprocher votre trafic premium par rapport à ces valeurs par requête plutôt que par rapport à un chiffre mensuel. La même valeur circule dans le header de réponse `X-FourA-Exit-Class` (voir [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**Le trafic premium est mesuré sur le réseau.** Une tentative premium comptabilise ce qu'elle a envoyé et reçu lors de son transit sur le réseau, compressé et chiffré en temps réel, qu'elle ait ou non renvoyé votre page. Une tentative encore en cours lorsqu'une autre sortie a répondu est arrêtée immédiatement, et le trafic acheminé jusque-là compte également. Le trafic premium est décompté de votre quota premium ainsi que de votre bande passante totale: les mêmes octets, rapportés deux fois, ne sont jamais additionnés. Lorsqu'une sortie premium a délivré la page, son trafic constitue l'intégralité du trafic de la requête, de sorte que la page n'est pas comptabilisée à nouveau comme trafic standard. Votre page [Usage & Limits](https://foura.ai/docs/dashboard/quota) affiche le trafic total, la part premium de celui-ci et le quota premium auquel vous êtes mesuré.

Omettre le champ et envoyer `standard` maintiennent tous deux la requête sur le pool standard: seul `premium` autorise une sortie premium. Une requête réussie qui spécifie une classe reçoit `exitClass` dans la réponse, et une requête qui omet le champ ne le reçoit pas.

**L'épuisement du quota n'est pas une erreur.** Une requête spécifiant `premium` après l'épuisement du quota continue de fonctionner: le pool standard la traite et la réponse indique `standard`. La seule exception concerne une requête spécifiant un [exit location](#exit-location): le pool standard ne peut pas l'honorer, elle est donc refusée.

`exitClass: premium` nécessite un forfait incluant des sorties premium. Avec un forfait qui n'en inclut pas, la requête n'utilise jamais de sortie premium: elle est refusée avec une erreur 403 contenant `X-FourA-Limit: plan_limit_premium` (voir [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits)), avant tout traitement.


### Emplacement de sortie

Une sortie premium peut partir d'un lieu situé dans un pays donné et conserver son adresse aussi longtemps que vous en avez besoin:

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

La response indique le point de sortie et le pays d'où elle provient :

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

Cet identifiant `proxy` conserve l'ensemble. Transmettez-le à Single ou Browser et la request partira du même endroit, sans aucun autre champ à ses côtés. Voir [Pinning an Exit](#pinning-an-exit).

Règles :

- L'un quelconque parmi `exitState`, `exitCity`, `exitAsn`, `exitOs` et `exitLifetimeMin` envoie la request exclusivement via des sorties premium. Aucune tentative n'est effectuée sur le pool standard, car il ne peut pas les honorer.
- Ils nécessitent `exitClass: premium`. Sans cela, la request est refusée avec une erreur 400 indiquant le champ en cause.
- `exitState`, `exitCity` et `exitAsn` existent au sein d'un seul pays, ils nécessitent donc exactement un pays dans `exitCountries`. `exitOs` et `exitLifetimeMin` fonctionnent avec plusieurs : la sortie en sélectionne un, et `exitCountry` dans la response indique lequel.
- `exitState`, `exitCity`, `exitAsn` et `exitOs` nécessitent un forfait incluant le ciblage géographique ainsi que les sorties premium.
- En l'absence de trafic premium restant, la request est refusée avec une erreur 403 contenant `X-FourA-Limit: plan_limit_premium`, car le pool standard ne peut pas la traiter.
- Si aucune sortie premium ne répond pour cet emplacement, la response est une enveloppe d'erreur identique à celle présentée sous [exitCountries scoping](#exitcountries-scoping), avec l'erreur `No premium exit answered for this request` et `code: no_eligible_proxy`. `details.exitCountries` est présent lorsque vous avez envoyé une liste de pays.

Les termes sont ceux que le [proxy port](https://foura.ai/docs/api/proxy-port) accepte pour `state`, `city`, `asn` et `os`.

### Rotation du profil de navigateur

Proxy applique une rotation aux sorties. Lorsqu'un site refuse le navigateur présenté par FourA plutôt que la sortie dont il provient, Proxy bascule également vers une autre famille de navigateurs du catalogue. Cela n'ajoute aucune tentative : la rotation modifie ce qu'envoie un nouvel essai, jamais le fait qu'il ait lieu ou non.

Proxy mémorise également, pendant un certain temps, la dernière famille acceptée par un site, afin qu'un appel ultérieur vers ce même site puisse commencer avec cette famille au lieu de celle par défaut. La response l'indique dans `profile`, tout comme elle le fait pour toute famille sélectionnée par la rotation.

Une valeur explicite pour `profile`, `browser`, `os` ou `version` sur votre `request` interne n'est jamais écrasée, pas plus qu'une request comportant son propre header `User-Agent` ou `Cookie`, car une autorisation est liée à la signature qui l'a obtenue.

---

## Browser Request

`POST /api/browser/`

Ouvre votre URL dans une instance de navigateur Chrome. La page se charge, le JavaScript s'exécute, et vous obtenez le HTML entièrement rendu ainsi que le cookie jar.

### Corps de la request

| Paramètre | Type | Requis | Par défaut | Description |
|-----------|------|----------|---------|-------------|
| `url` | string | Oui | - | URL cible |
| `headers` | object | Non | - | Headers personnalisés sous forme de paires clé-valeur |
| `cookies` | array | Non | - | Cookies à définir : `[{name, value, domain?}]` |
| `userAgent` | string | Non | - | Chaîne User-Agent personnalisée |
| `unblocker` | boolean | Non | `true` | Effectue la vérification requise par une page avant son chargement (page de challenge ou contrôle similaire). Activé par défaut. Définissez `false` pour afficher ce que la page renvoie tel quel, y compris une page de challenge. |
| `proxy` | string | Non | - | Identifiant de proxy d'une réponse précédente, pour conserver la même sortie. Renvoyez la chaîne opaque telle quelle. Une adresse proxy brute est rejetée avec `400 Invalid proxy format`. |
| `timeout_ms` | number | Non | 30000 | Délai d'attente de chargement de page en ms (max : 120000) |
| `checkStatus` | number | Non | - | Statut HTTP attendu (la requête échoue s'il est différent) |
| `checkText` | string | Non | - | Texte qui doit apparaître dans la page affichée |
| `lean` | boolean | Non | `false` | Exclut les images, les polices et les médias, ainsi que les requêtes vers les services connus de publicité, d'analyse, de consentement et de réseaux sociaux. La page elle-même, ses propres scripts et styles, ainsi que les éléments nécessaires à une étape de vérification continuent de se charger. Utilisez ce paramètre pour réduire la consommation de trafic d'une page, par exemple via une sortie premium dédiée. |

### Synchronisation de l'horloge du navigateur avec la sortie

Une page peut lire le fuseau horaire du navigateur et le comparer au pays de l'IP détectée. Une incohérence constitue l'un des signaux les plus simples exploités par un détecteur de bots, et vous pouvez l'éliminer sans coût supplémentaire.

Vous n'avez rien à faire. FourA extrait le pays depuis l'identifiant `proxy` et le navigateur indique un fuseau horaire correspondant.

- Il s'agit du pays de **sortie**, c'est-à-dire le pays vu par la cible, et non celui où le proxy est hébergé. Les deux divergent suffisamment souvent pour avoir une incidence.
- Lorsque FourA ne connaît pas le pays de sortie, il ne modifie pas l'horloge du navigateur au lieu d'émettre une supposition. Une sortie premium dispose d'un pays connu si vous en avez demandé un avec `exitCountries` dans [Proxy Request](#exit-location).
- Seule l'horloge s'aligne sur le pays. `Accept-Language` et le contenu renvoyé par le site restent intacts, ce qui évite tout changement de langue inattendu sur la page.

### Le paramètre `userAgent`

Transmettez `userAgent` et cette valeur exacte sera transmise à la page, à ses workers et à la cible. FourA en déduit également les client hints correspondants (`sec-ch-ua`, `sec-ch-ua-platform`, `navigator.platform`, ainsi que les valeurs à forte entropie explicitement demandées par un détecteur), afin que la requête ne déclare pas un navigateur dans le header et un autre en JavaScript.

Le `userAgent` renvoyé dans la réponse correspond à celui qui a été présenté. Cet élément est déterminant lors du rejeu d'une autorisation : un cookie `cf_clearance` est associé à la sortie et au User-Agent qui l'ont obtenu. Veillez donc à renvoyer la chaîne indiquée dans la réponse, et non celle que vous pensez avoir été utilisée. Consultez [Site checks](https://foura.ai/docs/api/site-checks).

Envoyez une chaîne non-Chromium (un User-Agent Firefox, par exemple) et elle est transmise telle quelle, sans aucune liste de marques Chromium associée.

### Exemple

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Réponse :

```json
{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `status` | number | Code de statut HTTP renvoyé par la cible |
| `headers` | object | En-têtes de réponse |
| `body` | string or object | Contenu de page entièrement rendu. Chaîne HTML lorsque le content-type est HTML; objet lorsque la page a renvoyé du JSON analysé automatiquement. |
| `cookies` | array | Objets cookie complets de la page. Chaque cookie inclut `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`, ainsi que d'autres propriétés de cookie. |
| `userAgent` | string | User-Agent du navigateur utilisé |
| `defenseSolved` | boolean | `true` si une protection anti-bot a été rencontrée et validée avec succès lors de cet appel, sinon `false`. Détermine si l'appel coûte 5 ou 10 crédits. |
| `defenses` | object | `present` liste chaque fournisseur identifié pendant le chargement de la page, `cleared` liste ceux dont la validation est conservée par la page finale. Un fournisseur peut apparaître dans `present` et jamais dans `cleared`. Voir [Vérifications de site](https://foura.ai/docs/api/site-checks). |
| `proxy` | string | Identifiant encodé du proxy emprunté par la requête (uniquement si un `proxy` a été fourni dans la requête). Réutilisez-le lors des appels suivants pour conserver la même sortie. |
| `error` | string | Message d'erreur en cas d'échec de la requête |

---

## Épingler une sortie

Une valeur `proxy` sur une requête Single ou Browser épingle la sortie utilisée lors d'un appel précédent. Renvoyez l'identifiant opaque exactement tel qu'il a été reçu, jamais une adresse de proxy. Un identifiant issu d'une requête Proxy ayant défini un pays, un lieu ou une durée de vie les conserve, la requête épinglée n'a donc besoin d'aucun autre champ.

Trois valeurs sont refusées, toutes avec une erreur 400 :

| Erreur | Signification |
|-------|---------|
| `Invalid proxy format` | La valeur n'est pas un identifiant émis par FourA. Une adresse de proxy brute aboutit ici. |
| `Proxy not found` | L'identifiant a été décodé, mais il ne correspond plus à une sortie active. Obtenez-en un nouveau via un nouvel appel. |
| `Managed exit: this proxy id cannot be pinned to a request` | La sortie existe, mais FourA ne peut pas la maintenir ouverte pour une requête ciblée. L'identifiant d'une sortie premium aboutit ici lorsque votre forfait n'a plus de trafic premium disponible. Réutilisez la session d'origine ou effectuez l'appel via `POST /api/proxy/` et acceptez la sortie sélectionnée. |

Une sortie premium épinglée est comptabilisée comme du trafic premium. La réponse inclut `X-FourA-Exit-Class: premium` afin que vous puissiez le vérifier par requête, et le trafic acheminé par la sortie est décompté du trafic premium sur votre page [Utilisation et limites](https://foura.ai/docs/dashboard/quota) ainsi que de votre bande passante totale, que le site ait renvoyé la page souhaitée ou non. L'épinglage nécessite des sorties premium incluses dans votre forfait et du quota restant; dans le cas contraire, l'identifiant est refusé avec l'erreur 400 managed-exit ci-dessus.

## Codes de statut HTTP

| Code | Signification |
|------|---------|
| 200 | Request aboutie (vérifiez le `status` interne pour la response cible) |
| 400 | Corps de request ou paramètres invalides, IP cible dans une plage privée/réservée, cible hébergée sur l'API même de FourA, URL contenant un espace non encodé (Single, Proxy, Auto), ou identifiant de proxy impossible à épingler. Sur Single, Proxy et Browser, un champ en échec de validation est indiqué : `Invalid request: <field>: <reason>`, jusqu'à cinq champs. Non facturé. Auto renvoie la même erreur avec HTTP 200 et `status: 400` dans le body. |
| 401 | Clé API manquante ou invalide |
| 403 | L'endpoint ou un paramètre n'est pas inclus dans votre forfait. `X-FourA-Limit` l'indique : `plan_limit_feature` ou `plan_limit_premium`. |
| 404 | `Not Found` : aucun endpoint n'existe sur ce chemin. |
| 413 | Le corps JSON de la request dépasse 100 Ko. La response n'est pas du JSON et ne contient aucun `X-FourA-Request-Id`. |
| 429 | Limite de forfait (`X-FourA-Limit` défini) ou quota partagé par minute de la plateforme (aucun header) |
| 500 | Erreur interne du serveur |
| 502 | `Upstream unavailable` : FourA n'a pas pu se connecter à son moteur. `Malformed JSON from backend` : le moteur a répondu mais FourA n'a pas pu lire la response. Réessayez. |
| 503 | Service temporairement désactivé ou saturé, `API key check temporarily unavailable` lorsque FourA n'a pas pu vérifier votre clé pendant un court instant (réessayez après `Retry-After`), ou `Backend service unavailable` pendant le redémarrage d'un moteur. Sur Browser, une page attend jusqu'à 10 secondes un navigateur disponible quand tous sont occupés, et reçoit `Backend service unavailable` si aucun ne se libère dans ce délai. |
| 504 | `Upstream timeout`. Le moteur n'a pas terminé dans le délai alloué pour cette request. Augmentez `timeout_ms` ou réessayez. |

## Étapes suivantes

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch) : Quand laisser FourA choisir la méthode pour vous
- [Choisir le bon endpoint](https://foura.ai/docs/guides/choosing-task-type) : Quand sélectionner manuellement Single, Proxy ou Browser
- [Authentification](https://foura.ai/docs/getting-started/authentication) : Gérer vos clés API
- [Gestion des erreurs](https://foura.ai/docs/api/errors) : Traiter les erreurs efficacement
- [Vérifications du site](https://foura.ai/docs/api/site-checks) : Lire le champ `defense` et rejouer une autorisation
- [Pourquoi une request Proxy a épuisé ses tentatives](https://foura.ai/docs/troubleshooting/proxy-attempt-report) : Lire `attemptReport` et agir en conséquence
- [Rate limits](https://foura.ai/docs/api/rate-limits) : Comprendre les limites de request
- [Démarrage rapide](https://foura.ai/docs/getting-started/quick-start) : Votre première request en 30 secondes
