# Provider Failover

HikerAPI is the primary MVP provider because it is closest to xskill's `twitterapi.io` role: API-key access to public social data, pay-per-request pricing, direct media lookup, comments, reels/clips, profile/search/hashtag/location surfaces, and no customer OAuth requirement. Apify remains a specialized fallback, especially for transcript experiments, and Bright Data remains a scale fallback skeleton until live account fixtures and schema verification exist.

## Configuration

Default order:

```text
IGSKILL_PROVIDER_ORDER=hikerapi,brightdata,apify
IGSKILL_PROVIDER_FAILOVER_ENABLED=true
```

Disable automatic failover:

```text
IGSKILL_PROVIDER_FAILOVER_ENABLED=false
```

Prefer Bright Data first after it is verified:

```text
IGSKILL_PROVIDER_ORDER=brightdata,hikerapi,apify
IGSKILL_PROVIDER_FAILOVER_ENABLED=true
```

## Behavior

- Routes call the shared normalized `InstagramProvider` interface.
- Retryable provider failures can advance to the next configured provider.
- Non-retryable provider failures stop immediately.
- Responses that use fallback include a `provider_failover_used` limitation.
- Public pricing stays on the igskill price card, not raw provider cost.
- Provider raw errors and secrets must not be returned to callers.

## Rollback

Rollback is config-only:

```text
IGSKILL_PROVIDER_ORDER=hikerapi,brightdata,apify
IGSKILL_PROVIDER_FAILOVER_ENABLED=false
```

After any provider-order change, run post, reel, and comments smoke checks. If limitations increase or result shapes change, roll back and capture fixtures before changing public behavior. HikerAPI does not currently provide a verified reel speech transcript field in the tested schema, so transcript=true still requires the hosted transcription fallback.