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/mcpencapsule 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 optionoffload_largepour une gestion optimisée des réponses volumineuses en termes de tokens. Les différences :foura_browsern'a pas de champlean, etfoura_proxyne 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.acceptavec 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
404ou410et que votrevalidatene l'accepte pas, l'appel se termine avec cestatuset unerrorqui commence parthe site answered. Listez le statut dansvalidate.status.acceptet Auto renvoie la première réponse avec ce statut qui valide le reste de vosvalidate. Il en va de même pour tout autre statut que vous y listez, sauf403,429,503et202, que les sites envoient également avec une page de challenge. timeout_msplafonne 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). Avecunblockerdé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
profileinconnu renvoieunknown 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
requestdePOST /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,exitOsetexitLifetimeMinenvoie 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,exitCityetexitAsnexistent au sein d'un seul pays, ils nécessitent donc exactement un pays dansexitCountries.exitOsetexitLifetimeMinfonctionnent avec plusieurs : la sortie en sélectionne un, etexitCountrydans la response indique lequel.exitState,exitCity,exitAsnetexitOsné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 requestetcode: no_eligible_proxy.details.exitCountriesest 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
exitCountriesdans Proxy Request. - Seule l'horloge s'aligne sur le pays.
Accept-Languageet 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
- Smart Fetch (Auto) : Quand laisser FourA choisir la méthode pour vous
- Choisir le bon endpoint : Quand sélectionner manuellement Single, Proxy ou Browser
- Authentification : Gérer vos clés API
- Gestion des erreurs : Traiter les erreurs efficacement
- Vérifications du site : Lire le champ
defenseet rejouer une autorisation - Pourquoi une request Proxy a épuisé ses tentatives : Lire
attemptReportet agir en conséquence - Rate limits : Comprendre les limites de request
- Démarrage rapide : Votre première request en 30 secondes