Smart Fetch (Auto)

FourA에 URL과 실제 페이지에 포함되어야 할 내용에 대한 validate 규칙을 전달합니다. 이후 작업은 FourA가 처리합니다. 비용을 고려한 단계를 순차적으로 진행하며, 규칙에 부합하는 응답을 반환하는 첫 번째 단계에서 중단합니다. 또한 호스트별로 성공한 방식을 기억하여 동일한 사이트에 대한 다음 호출 비용을 절감합니다.

이 가이드에서는 auto 기능의 내부 작동 방식, 사용 시점 및 응답을 해석하는 방법을 설명합니다. 매개변수 참조는 API Endpoints를 참고하십시오.

기본 개념

대부분의 스크래핑 환경에서는 엔진을 사전에 직접 선택해야 합니다. Single은 가장 빠르고, Proxy는 로테이션을 추가하며, Browser는 JavaScript를 처리합니다. 엔진을 잘못 선택하면 크레딧이 낭비되거나 차단될 수 있습니다.

Auto는 이 방식을 전환합니다. 방식 대신 성공 조건(validate)을 정의합니다. FourA는 성공할 때까지 다음 단계를 순서대로 실행합니다.

저비용 탐색 (FourA 자체 네트워크를 통한 single 직접 요청)
Browser (사이트 챌린지가 발생할 경우 JavaScript 및 솔버를 포함하여 FourA 자체 네트워크에서 직접 실행)
로테이션 proxy single
최고 난도 대상을 위한 proxy 경유 Browser

Auto는 특정 단계에서 validate 규칙을 충족하는 응답을 반환하는 즉시 중단됩니다.

이 순서 외에 별도로 동작하는 단계가 하나 있습니다. 출구 노드가 사이트에 도달했으나 요청한 딥 URL에 대한 접근이 거부된 경우, auto는 동일한 출구를 통해 해당 사이트의 진입 페이지를 가져옵니다. 그런 다음 진입 페이지에서 발급된 cookie를 유지한 상태로 해당 cookie를 포함하여 원래 URL을 다시 요청합니다. 이것이 바로 warmup 단계입니다. 이 단계는 사이트 루트보다 깊은 URL에서 직접 시도가 이미 실패한 경우에만 실행되며, 결과를 추가할 뿐 기존 결과를 없애지 않습니다.

forceProxy 기본값은 true이므로 1단계와 2단계는 건너뛰며 대상 사이트에 FourA 자체 주소가 노출되지 않습니다. 따라서 대부분의 호출은 3단계 또는 재사용된 웜 세션에서 완료됩니다. 대상 사이트가 로테이션 주소보다 클린 주소를 더 원활하게 처리하는 경우 forceProxy: false를 설정하면 1단계와 2단계가 다시 활성화됩니다.

전송해야 하는 항목

최소 요구 사항은 URL과 validate 하위 문자열입니다. Auto는 일반적인 챌린지 페이지를 자체적으로 인식하지만, validate.data.accept이 없으면 실제 페이지와 알 수 없는 확인 페이지를 구분할 수 없거나 콘텐츠 없이 로드된 페이지를 구분하지 못해 이를 성공으로 반환할 수 있습니다.

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"]}}
  }'

선택적 설정값 (자세한 내용은 endpoint 레퍼런스 참조):

returnSession (기본값 true): 다시 실행할 수 있도록 성공한 { proxy, cookies, userAgent }를 반환합니다.
forceProxy (기본값 true): 직접 이그레스 단계를 건너뜁니다. 대상 사이트가 무료 순환 프록시보다 클린 IP에 더 우호적인 경우에만 false로 설정하십시오.
timeout_ms (기본값 120000): 전체 호출에 대한 총 예산입니다. 래더가 각 단계별로 이를 배분합니다.
ignoreProxies: 모든 하위 시도에서 제외할 프록시 ID 목록입니다.
followRedirects (기본값 5): 저비용 단계에서의 최대 리디렉션 횟수입니다.

응답 결과

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

확인해야 할 세 가지 항목:

status 및 data: 타깃의 응답입니다. data는 모든 단계에서 텍스트로 제공됩니다. 브라우저가 전달한 경우에도 JSON 페이지는 JSON 문자열로 반환되므로 클라이언트 측에서 직접 파싱해야 합니다. status은 FourA 호출에 대한 전송 상태가 아닌 타깃의 HTTP 상태 코드입니다. single 및 proxy 단계의 경우 headers은 홉(hop)별 배열입니다. browser 단계의 경우 headers은 플랫 객체입니다.
meta: 래더가 시작된 후 모든 응답에 포함되는 래더 동작 추적 정보입니다. meta.rung은 응답을 전달한 단계를 나타내고, meta.attempts은 하위 호출 재시도 횟수를 계산하며, meta.solved는 챌린지 페이지 완료 여부를 표시하고, meta.credits은 해당 호출의 총 비용입니다(X-FourA-Credits 헤더와 동일한 값).
session: 타깃을 성공적으로 처리한 { proxy, cookies, userAgent } 3종 조합입니다. 이를 사용하여 /api/single/ 또는 /api/browser/를 통해 동일한 호스트에 다시 요청을 실행할 수 있습니다.

모든 단계가 실패하더라도 래더가 실행된 경우에는 Auto가 항상 HTTP 200으로 응답합니다. 전송 상태 코드가 아닌 본문의 status 및 error을 읽어 결과를 확인하십시오. /api/auto/에서 반환된 200 이외의 코드는 호출이 래더에 도달하지 못했음을 의미합니다. 잘못된 키는 401, 유효하지 않은 JSON 본문이거나 프라이빗 네트워크의 타깃인 경우는 400, 서비스가 호출을 수락할 수 없거나 시간이 초과된 경우는 502, 503 또는 504가 반환됩니다. Auto는 게이트웨이에서 슬롯을 차지하지 않으므로 플랫폼의 공유 한도로 인해 호출 자체가 거부되지 않습니다. 래더가 시도한 호출이 한도에 의해 거부되면 응답은 본문에 status: 429 또는 503 및 retryAfter가 포함된 HTTP 200으로 반환됩니다. 유효성 검사에 실패한 필드 역시 status: 400와 함께 HTTP 200으로 반환됩니다. 래더 내부에서 플랜 한도에 도달한 경우에도 거부 사유가 본문에 포함된 채 HTTP 200으로 반환됩니다(플랜 한도와 래더 동작 방식 참조).

Session으로 다시 요청 실행하기

Auto가 session을 반환한 후에는 동일한 호스트의 후속 페이지에 대해 Single 또는 Browser로 바로 진입할 수 있습니다. 새로운 래더 실행이나 추가 프로브가 필요하지 않습니다.

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

세션의 유효 기간은 대상 사이트의 설정에 따라 결정됩니다. 어떤 사이트는 몇 시간 동안 쿠키 저장소에 통과 상태를 유지하지만, 몇 분마다 갱신하는 사이트도 있습니다. 재실행 시 다시 challenge가 반환되기 시작하면 /api/auto/를 한 번 더 호출하여 갱신하십시오.

Auto를 사용해야 하는 경우

Auto 사용	직접 single, proxy, browser 사용
새로운 사이트를 대상으로 하며 요구 사항을 모르는 경우	작동하는 엔진을 이미 알고 있는 경우
직접 연결, proxy, browser 대체 처리를 한 번의 호출로 해결하려는 경우	호출별 재시도 및 타임아웃을 완전히 제어하려는 경우
첫 호출에서 몇 초간의 탐색 시간을 감수할 수 있는 경우	탐색보다 첫 호출의 지연 시간이 더 중요한 경우
저렴하게 재실행할 수 있는 학습된 세션이 필요한 경우	정상 작동이 확인된 대상에 대해 긴밀한 루프를 최적화하는 경우

Auto가 항상 가장 경제적인 선택은 아닙니다. 대상이 single + unblocker 환경에서 작동한다는 점을 알고 있다면, Single을 직접 호출하는 것이 예측 가능한 지연 시간과 함께 2 크레딧만 소모됩니다. 동일한 대상에 Auto를 사용하면 단계별 탐색에 필요한 비용이 발생하며 사이트가 단계적 확장을 요구할 경우 비용이 더 늘어날 수 있습니다.

Validate를 통해 Auto에 "성공"의 의미 전달

가장 중요한 매개변수는 validate입니다. 이 매개변수가 없으면 auto는 인식 가능한 challenge 페이지만 거부하므로, 낯선 확인 페이지나 HTTP 200과 함께 반환된 빈 껍데기 응답도 정상 콘텐츠로 통과시킵니다.

실제 페이지만 포함하는 하위 문자열을 지정하여 validate.data.accept를 사용하십시오.

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

JSON API의 경우, 예상되는 필드 이름을 수락합니다:

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

합법적으로 non-200을 반환하는 사이트(무시하려는 국가 제한, 로그아웃된 endpoint의 의도적인 403 등)의 경우, validate.status.accept을 통해 허용합니다:

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

validate이 없으면 auto는 챌린지로 인식하지 못한 모든 페이지에 대해 "HTTP 200 = 성공"으로 폴백하므로, 사이트가 200과 함께 반환하는 낯선 확인 페이지를 감지하지 못합니다.

발생한 문제를 파악하기 위해 `meta.rung` 확인하기

meta.rung는 가장 유용한 디버그 신호입니다. 값:

probe - 비용이 적게 드는 직접 request로 해결되었습니다. 가장 저렴한 경로입니다.
proxy - 통과를 위해 proxy 교체가 필요했습니다.
browser - 챌린지 해결을 포함할 수 있는 전체 브라우저 렌더링이 필요했습니다.
cache - 이전 auto 호출의 웜 세션을 재사용했습니다. 반복 호출 시 가장 저렴한 경로입니다.
warmup - 사이트가 진입 페이지를 제공했지만 딥 URL을 차단하여, auto가 먼저 진입 페이지를 가져와 발급된 cookie를 유지한 후 이를 사용하여 다시 요청했습니다. 이 단계에서 저장된 세션은 단일 출구에 묶이지 않으므로 후속 호출은 저렴한 단계로 연결됩니다.
fail - 사용자의 규칙을 충족하는 응답을 생성한 단계가 없습니다.

meta.solved: true는 호출 중에 챌린지 페이지를 만나 완료했음을 의미합니다. meta.attempts은 성공하기 전까지 시도한 하위 호출 횟수입니다. 이에 대한 자세한 내용은 단일 및 proxy 단계가 반환하는 defense 필드를 확인하세요. Site checks를 참조하세요.

사이트가 probe을 예상했을 때 계속 browser로 끝난다면, 더 엄격한(또는 덜 엄격한) validate 규칙을 통해 더 저렴한 단계를 통과시킬 수 있는지 고려해 보세요. forceProxy의 기본값은 true이므로 직접 egress 프로브를 비활성화하지 않는 한 건너뛴다는 점을 유의하세요.

오류 및 예외 케이스

auto가 실패하면 response에 status(보통 마지막으로 실패한 단계의 상태)와 error 문자열이 포함됩니다.

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status는 auto가 거부된 마지막 시도에서 사이트가 반환한 응답(예: 403)입니다. 어떤 시도에서도 사이트의 응답을 전혀 받지 못한 경우 대개 502 또는 504이며, error는 작동하는 exit를 찾지 못했는지 또는 timeout_ms 예산이 소진되었는지를 나타냅니다. status: 0는 타겟의 호스트 이름이 확인되지 않았음을 의미할 뿐이며, 래더가 시작조차 되지 않았으므로 해당 응답에는 meta가 없습니다.

예산이 어디에 사용되었는지 확인하려면 meta.attempts 및 meta.credits를 확인하십시오. meta.attempts가 높고 브라우저 단계 이후 meta.rung가 fail인 경우, 타겟에 더 긴 timeout_ms, 더 엄격한 validate 규칙이 필요하거나 현재 순환 proxy를 통해 접근할 수 없는 상태일 수 있습니다.

플랜 제한이 래더에 적용될 때

Auto의 하위 호출은 사용자의 키로 실행되는 일반적인 Single, Proxy 및 Browser request이므로, 사용자의 플랜 제한이 그대로 적용됩니다. 래더는 거부 시 X-FourA-Limit 코드를 읽고 두 가지 유형을 다르게 처리합니다.

특정 단계가 닫혀도 래더의 나머지 단계는 계속 사용할 수 있습니다. plan_limit_browser_daily(해당 일의 Browser request 사용량 소진) 및 plan_limit_concurrency(해당 endpoint에서 플랜이 허용하는 최대 동시 request 수 도달)는 한 단계를 닫습니다. Auto는 다른 단계를 계속 시도하므로 순환 exit 또는 웜 세션이 콘텐츠를 제공하는 한 페이지를 계속 수신할 수 있으며, 시도한 exit는 사용자 플랜에서 발생한 거부에 대해 책임을 지지 않습니다. 아무것도 차단되지 않으며 세션도 폐기되지 않습니다.

계정 한도가 소진되면 래더가 중단됩니다. plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature 및 plan_limit_premium는 다른 단계로 해결할 수 없으므로, auto는 이를 확인하느라 크레딧을 더 소비하는 대신 즉시 결과를 반환합니다. 거부 응답은 하위 호출의 상태 및 직접 endpoint가 사용하는 것과 동일한 reason 필드와 함께 body에 반환됩니다.

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

서브 호출의 전체 거부 본문이 그대로 전달되며, status 및 meta도 함께 포함됩니다. 전송 상태가 아닌 본문에서 status을 확인하십시오. 래더가 실행되었으므로 auto는 여전히 HTTP 200으로 응답합니다. plan_limit_feature 또는 plan_limit_premium 거부 또한 status: 403와 함께 동일한 방식으로 도달합니다. 거부된 서브 호출은 비용이 청구되지 않으므로, meta.credits는 타깃에 도달한 단계만 계산합니다.

단일 auto 호출이 래더를 진행하는 동안 여러 슬롯을 점유할 수 있으므로, auto 호출을 병렬 배치로 실행하면 예상보다 적은 호출 수로도 동시성 상한에 도달할 수 있습니다. 배치 크기 조정 방법은 병렬 요청 실행에서 다룹니다.

Auto가 수행하지 않는 작업

법적 제한을 변경하지 않습니다. FourA가 접근할 수 있는 모든 출구를 사이트가 거부하면 auto는 해당 거부 응답을 반환합니다.
콘텐츠를 캐시하지 않습니다. 모든 호출은 여전히 타깃에 직접 도달합니다. "웜 세션"은 프록시 및 쿠키를 의미하며 응답 자체를 의미하지 않습니다.
Activity Log에서 수신한 request id 아래에 서브 호출의 크레딧 합계와 함께 단일 행으로 표시됩니다. 해당 행을 열면 auto가 대신 실행한 Single / Proxy / Browser 서브 호출이 각각의 결과와 함께 시도 내역으로 나열됩니다. 이들은 Single, Proxy, Browser 제한에는 반영되지만 요청 수나 성공률에는 반영되지 않습니다.