Référence des endpoints API

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 :

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. 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 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 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. Indiquez-le lorsque vous contactez le support pour identifier la requête en quelques secondes.

$ 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 pour la liste complète et les conseils d'utilisation.

Endpoints

Vous utilisez ces endpoints via MCP ? Le serveur @fouradata/mcp 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.

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 et le guide 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.

{ "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.

{ "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. 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.

Response

{
  "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.

Exemple

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 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 : 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.
browser string Non Chrome Navigateur à présenter : Chrome, Edge, Safari, Firefox ou Tor. Voir 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.

{
  "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 :

{
  "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.

{
  "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

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 :

{
  "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 :

{
  "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 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.
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 :

{
  "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

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 :

{
  "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 :

{
  "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.

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.

{
  "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 :

{
  "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).

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 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: 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), 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:

{
  "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 :

{
  "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.

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, 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 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.
  • 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.

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

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 :

{
  "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.
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 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

Mis à jour : 13 novembre 2026