# 올바른 엔드포인트 선택하기

> URL: https://foura.ai/ko/docs/guides/choosing-task-type
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

FourA는 서로 다른 시나리오에 최적화된 4개의 request endpoint를 제공합니다. 적절한 endpoint를 선택하면 시간을 절약하고 비용을 줄이며 성공률을 높일 수 있습니다.

## 빠른 결정 가이드

**다음과 같은 경우 auto endpoint를 사용하세요:**
- 새로운 사이트를 대상으로 하며 어떤 설정이 필요한지 아직 모르는 경우
- proxy 순환 및 브라우저 fallback을 자동으로 처리하는 단일 호출을 원하는 경우
- 동일한 호스트에 대한 다음 호출 시 저렴하게 재사용할 수 있는 세션이 필요한 경우

**다음과 같은 경우 single endpoint를 사용하세요:**
- 페이지가 서버 렌더링되는 경우 (JavaScript 불필요)
- 최대 속도가 필요한 경우 (일반적으로 1초 미만)
- 정상 작동이 확인된 호스트의 API 또는 정적 HTML 페이지를 호출하는 경우

**다음과 같은 경우 browser endpoint를 사용하세요:**
- 페이지 콘텐츠 렌더링에 JavaScript가 필요한 경우
- 초기 페이지 로드 이후 콘텐츠가 로드되는 경우
- 완전히 렌더링된 DOM이 필요한 경우

**다음과 같은 경우 proxy endpoint를 사용하세요:**
- 대상 사이트가 request를 적극적으로 차단하는 경우
- 여러 IP 주소를 순환해야 하는 경우
- 이전 시도에서 403 또는 인증 페이지가 반환된 경우

## Endpoint 비교

### Auto (`POST /api/auto/`)

스마트 fetch endpoint입니다. URL과 함께 가급적 `validate` 규칙을 전달하면 FourA가 비용을 고려한 단계별 절차를 진행합니다. 순환 proxy를 먼저 시도하고, 이후 proxy를 통한 전체 브라우저를 시도합니다. `forceProxy: false`을 설정하면 두 단계 전에 저렴한 직접 프로브 및 직접 브라우저 렌더링이 먼저 실행됩니다. `validate`와 일치하는 response를 반환하는 첫 번째 단계가 적용됩니다. 동일한 호스트에 대한 반복 호출 시에는 warm 세션이 재생되므로 두 번째 호출부터 비용이 저렴합니다.

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

**일반적인 응답 시간:** 200ms (웜) ~ 30초 이상 (난이도 높은 사이트의 콜드 해결)
**권장 대상:** 새로운 타깃, 다양한 보호 수준이 혼재된 사이트, 빠른 페이지 획득 필요 시

자세한 안내는 [Smart Fetch 가이드](https://foura.ai/docs/guides/smart-fetch)를 참고하십시오.

### Single (`POST /api/single/`)

가장 빠른 옵션입니다. 브라우저 프로세스를 실행하지 않고 실제 브라우저와 유사한 네트워크 특성을 가진 HTTP 요청을 전송합니다.

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

**일반적인 response 시간:** 200ms ~ 2s
**적합한 대상:** API, 뉴스 사이트, 블로그, 정적 제품 페이지

### 브라우저 (`POST /api/browser/`)

Chrome 브라우저 인스턴스에서 URL을 엽니다. 페이지가 완전히 로드되고 JavaScript가 실행된 후 최종 렌더링된 HTML을 반환합니다.

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

**일반적인 response 시간:** 2초 ~ 10초
**적합한 용도:** 단일 페이지 애플리케이션(SPA), 지연 로딩을 사용하는 사이트, JavaScript 렌더링 콘텐츠

### Proxy (`POST /api/proxy/`)

HTTP request와 자동 proxy 순환을 결합합니다. 첫 번째 시도가 실패하거나 차단되면 FourA가 서로 다른 proxy를 통해 재시도합니다.

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

**일반적인 응답 시간:** 1초~5초
**적합한 작업:** 이커머스 가격 모니터링, 여행 정보 애그리게이션, 봇 감지 기능이 있는 사이트

## Auto 대 Manual

언제 auto에 맡기고, 언제 Single, Proxy, Browser를 직접 호출해야 할까요?

| Auto 선택 | Manual 선택 |
|-----------|-------------|
| 사이트에 무엇이 필요한지 아직 모르는 경우 | 대상 사이트에 필요한 엔진을 정확히 알고 있는 경우 |
| 바로 작동하는 단일 호출을 원하는 경우 | 알려진 대상을 위해 request 형태를 최적화하는 경우 |
| auto가 학습한 세션을 재사용해도 무방한 경우 | 호출별 재시도, timeout, proxy 선택을 완전히 제어하려는 경우 |
| 첫 번째 호출에서 몇 초간의 탐색 비용을 감수할 수 있는 경우 | 탐색보다 첫 번째 호출의 지연 시간(latency)이 더 중요한 경우 |

Auto가 항상 더 저렴한 선택은 아닙니다. 대상이 Single 및 `unblocker` 활성화 상태로 작동함을 이미 알고 있다면, Single을 직접 호출하여 ladder 단계를 건너뛰고 2 크레딧만 소비할 수 있습니다. 동일한 대상에 auto를 사용하면 ladder가 소비한 만큼의 비용이 청구됩니다.

## 접근 방식을 조합하는 경우

일부 워크플로는 여러 endpoint를 결합하여 이점을 얻습니다:

1. **auto로 탐색**: `validate` 규칙을 전달하고 ladder가 사이트에 필요한 단계를 파악하도록 합니다.
2. **single로 재생(replay)**: auto가 반환한 `session.proxy`, `session.cookies`, `session.userAgent`를 가져와 동일한 호스트의 후속 페이지에 Single과 함께 호출합니다.
3. **browser로 폴백**: single 호출이 실패하기 시작하면 browser 렌더링으로 전환합니다.
4. **proxy 추가**: auto 없이 접근 거부(403 또는 인증 페이지)가 발생하는 경우, 자동 순환을 위해 proxy endpoint로 request를 감쌉니다.

이러한 점진적 접근 방식은 비용을 낮게 유지하면서 성공률을 높입니다.

## 성능 팁

- 보호된 대상에는 `validate.data.accept` 부분 문자열을 전달하세요. Auto는 일반적인 챌린지 페이지를 스스로 인식하지만, 파악되지 않은 확인 페이지나 필요한 콘텐츠 없이 로드된 페이지는 사용자 규칙으로만 감지할 수 있습니다.
- 정상 작동이 확인된 호스트에는 기본적으로 single endpoint를 사용하고, 필요할 때만 업그레이드하세요.
- browser request에 `checkText`를 설정하여 콘텐츠 없이 렌더링된 페이지가 성공 대신 실패(`checkText:<text> not found`)로 반환되도록 하세요. `checkText`는 FourA가 텍스트를 더 오래 기다리도록 만들지 않습니다.
- 재시도 동작을 제어하려면 proxy request에 `maxTries`를 설정하세요(기본값은 5, 최대값은 90).
- `timeout_ms` 값을 합리적으로 유지하세요: 대부분의 페이지는 10~15초, 보호된 사이트에 대한 콜드 auto 실행은 30초 이상을 권장합니다.

## 다음 단계

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): `/api/auto/` 심층 가이드
- [API Endpoints](https://foura.ai/docs/api/endpoints): 전체 파라미터 레퍼런스
- [동적 웹사이트 스크래핑](https://foura.ai/docs/how-to/scrape-dynamic-website): 단계별 browser request 가이드
- [빠른 시작](https://foura.ai/docs/getting-started/quick-start): 30초 만에 첫 request 보내기
