> ## Documentation Index
> Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Answers to common Skyvern questions covering troubleshooting failed tasks, agent parameters, credentials, scheduling, proxy configuration, API polling, data extraction, and LLM model selection.

## Troubleshooting

<Accordion title="Why did my task fail or terminate?">
  Check these in order:

  1. **Run status**: Use `get_run(run_id)` to see the status and `failure_reason`
  2. **Timeline**: Use `get_run_timeline(run_id)` to find which block failed
  3. **Artifacts**: Check `screenshot_final` to see where it stopped, and `recording` to watch what happened

  Common causes:

  * **`terminated`**: The AI couldn't complete the goal (CAPTCHA, login blocked, element not found)
  * **`timed_out`**: Exceeded `max_steps`. Increase it or simplify the task
  * **`failed`**: System error (browser crash, network failure)

  See the [Troubleshooting Guide](/developers/debugging/troubleshooting-guide) for detailed steps.
</Accordion>

<Accordion title="Why is the AI clicking the wrong element?">
  Multiple similar elements on the page can confuse the AI. Fix this by:

  1. **Add visual context**: "Click the **blue** Submit button at the **bottom** of the form"
  2. **Reference surrounding text**: "Click Download in the row that says 'January 2024'"
  3. **Be specific about position**: "Click the first result" or "Click the link in the header"

  Check the `llm_response_parsed` artifact to see what action the AI decided to take.
</Accordion>

<Accordion title="Why is my task timing out?">
  Tasks time out when they exceed `max_steps` (default: 50). This happens when:

  * The task is too complex for the step limit
  * The AI gets stuck in a navigation loop
  * Missing completion criteria causes infinite attempts

  **Fixes:**

  * Increase `max_steps` in your task parameters
  * Add explicit completion criteria: "COMPLETE when you see 'Order confirmed'"
  * Break complex tasks into multiple agent blocks
</Accordion>

<Accordion title="Why can't Skyvern find an element on the page?">
  Elements may not be detected if they:

  * Load dynamically after the page appears
  * Are inside an iframe
  * Require scrolling to become visible
  * Use unusual rendering (canvas, shadow DOM)

  **Fixes:**

  * Add `max_screenshot_scrolls` to capture lazy-loaded content
  * Describe elements visually rather than by technical properties
  * Add explicit wait or scroll instructions in your prompt
</Accordion>

<Accordion title="Why is the extracted data wrong or incomplete?">
  Check the `screenshot_final` artifact to verify the AI ended on the right page.

  Common causes:

  * Prompt was ambiguous about what to extract
  * `data_extraction_schema` descriptions weren't specific enough
  * Multiple similar elements and the AI picked the wrong one

  **Fixes:**

  * Add specific descriptions: `"description": "The price in USD, without currency symbol"`
  * Add visual hints: "The price is displayed in bold below the product title"
</Accordion>

***

## Agents

<Accordion title="How do I pass parameters to an agent?">
  Define parameters in the agent editor, then pass them when starting a run:

  ```python theme={null}
  result = await client.run_workflow(
      workflow_id="wpid_123456",
      parameters={
          "url": "https://example.com",
          "username": "user@example.com"
      }
  )
  ```

  Parameters are available in prompts using `{{ parameter_name }}` syntax. See [Agent Parameters](/cloud/building-agents/add-parameters) for details.
</Accordion>

<Accordion title="How do I use credentials in an agent?">
  1. **Store credentials**: Go to Settings > Credentials and add your login
  2. **Reference in agent**: Select the credential in the Login block's credential dropdown
  3. **Never hardcode**: Don't put passwords directly in prompts

  The AI will automatically fill the credential fields when it encounters a login form. See [Credentials](/sdk-reference/credentials) for setup instructions.
</Accordion>

<Accordion title="Can I run agents on a schedule?">
  Yes. Skyvern has built-in cron-based scheduling for agents. You define a cron expression and timezone, and Skyvern triggers the agent automatically at each interval.

  * **Cloud UI**: Create and manage schedules from the [Schedules page](/cloud/building-agents/scheduling)
  * **API**: Use the [scheduling API](/cloud/building-agents/run-from-code#create-a-schedule) to create, update, enable/disable, and delete schedules programmatically

  Scheduled runs appear in [Run History](/cloud/viewing-results/run-history) with a calendar icon badge. Set up a [webhook](/developers/going-to-production/webhooks) to get notified when scheduled runs complete.
</Accordion>

<Accordion title="Why isn't my agent using the parameter values I passed?">
  Make sure you're using the parameter placeholder syntax correctly:

  * **Correct:** `{{ parameter_name }}`
  * **Wrong:** `{parameter_name}` or `$parameter_name`

  Also verify:

  * The parameter name matches exactly (case-sensitive)
  * The parameter is defined in the agent's parameter list
  * You're passing the parameter when starting the run, not after
</Accordion>

<Accordion title="How do I run agents sequentially with the same credentials?">
  Use the "Prevent Overlapping Runs" option with a credential key:

  1. Enable "Prevent Overlapping Runs" in agent settings
  2. Set the sequential key to your credential identifier
  3. Skyvern will queue runs that share the same credential

  This prevents concurrent logins that could trigger security blocks.
</Accordion>

***

## Configuration

<Accordion title="Where do I find my API key?">
  Go to [Settings](https://app.skyvern.com/settings) in the Skyvern Cloud UI. Your API key is displayed there.

  For local installations, run `skyvern init` to generate a local API key, which will be saved in your `.env` file.
</Accordion>

<Accordion title="How do I change the LLM model?">
  **Cloud:** The model is managed by Skyvern. Contact support for custom model requirements.

  **Self-hosted:** Run `skyvern init llm` to reconfigure, or set these environment variables:

  * `LLM_KEY`: Primary model (e.g., `OPENAI_GPT5_5`, `ANTHROPIC_CLAUDE4.7_OPUS`)
  * `SECONDARY_LLM_KEY`: Optional lightweight model for faster operations
</Accordion>

<Accordion title="How do I configure proxy settings?">
  Set `proxy_location` when running a task:

  ```python theme={null}
  result = await client.run_task(
      prompt="...",
      url="https://example.com",
      proxy_location="RESIDENTIAL_US"  # or RESIDENTIAL_ISP for static IPs
  )
  ```

  Available locations include `RESIDENTIAL_US`, `RESIDENTIAL_UK`, `RESIDENTIAL_ISP`, and more. Use `RESIDENTIAL_ISP` for sites that require consistent IP addresses.
</Accordion>

<Accordion title="Can I increase the max steps limit beyond 75?">
  Yes. Contact support to increase the limit for your account. Higher limits may incur additional costs.

  Alternatively, break complex tasks into multiple agent blocks, each with its own step budget.
</Accordion>

***

## API & Integration

<Accordion title="How do I poll for task completion?">
  Check the run status in a loop:

  ```python theme={null}
  while True:
      run = await client.get_run(run_id)
      if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
          break
      await asyncio.sleep(5)
  ```

  Or use [webhooks](/developers/going-to-production/webhooks) to get notified when runs complete without polling.
</Accordion>

<Accordion title="Where can I find extracted data after a run completes?">
  The extracted data is in `run.output`:

  ```python theme={null}
  run = await client.get_run(run_id)
  print(run.output)  # {"field1": "value1", "field2": "value2"}
  ```

  For downloaded files, check `run.downloaded_files` which contains signed URLs.
</Accordion>

<Accordion title="How do I get the recording URL from the API?">
  The recording URL is included in the run response:

  ```python theme={null}
  run = await client.get_run(run_id)
  print(run.recording_url)  # https://skyvern-artifacts.s3.amazonaws.com/.../recording.webm
  ```

  Note: Signed URLs expire after 24 hours. Request fresh URLs if expired.
</Accordion>

<Accordion title="How do I trigger an agent via API?">
  Use the `run_workflow` method:

  ```python theme={null}
  result = await client.run_workflow(
      workflow_id="wpid_123456",
      parameters={"key": "value"}
  )
  print(result.run_id)  # wr_789012
  ```

  The agent starts asynchronously. Poll the run status or configure a webhook to track completion.
</Accordion>

***

## Authentication & Credentials

<Accordion title="Why is my login failing?">
  Check these common causes:

  1. **Credentials expired**: Verify username/password in your credential store
  2. **CAPTCHA appeared**: Use a browser profile with an existing session
  3. **MFA required**: Configure TOTP if the site requires 2FA
  4. **Site detected automation**: Use `RESIDENTIAL_ISP` proxy for trusted IPs

  Watch the `recording` artifact to see exactly what happened during login.
</Accordion>

<Accordion title="How do I handle CAPTCHA?">
  Options to bypass CAPTCHAs:

  1. **Browser profile**: Create a profile with an authenticated session that skips login entirely
  2. **Human interaction block**: Pause the agent for manual CAPTCHA solving
  3. **Residential proxy**: Use `RESIDENTIAL_ISP` for static IPs that sites trust more

  Skyvern has built-in CAPTCHA solving for common types, but some sites use advanced anti-bot measures.
</Accordion>

<Accordion title="How do I set up 2FA/TOTP?">
  1. Go to Settings > Credentials
  2. Create a new TOTP credential with your authenticator secret
  3. Reference the TOTP credential in your agent's login block

  The AI will automatically fetch and enter the TOTP code when it encounters a 2FA prompt. See [TOTP Setup](/developers/credentials/totp) for detailed instructions.
</Accordion>

<Accordion title="How do I handle email OTP verification?">
  Email OTP requires an external integration:

  1. Set up an email listener (Zapier, custom webhook, etc.)
  2. When the OTP arrives, send it back to Skyvern via the API
  3. Use a Human Interaction block to wait for the code

  Alternatively, check if the site supports TOTP authenticators, which Skyvern handles natively.
</Accordion>

***

## Browser & Proxy

<Accordion title="Why is the site blocking Skyvern?">
  Sites may detect automation through:

  * IP reputation (datacenter IPs are often blocked)
  * Browser fingerprinting
  * Rate limiting

  **Fixes:**

  * Use `RESIDENTIAL_ISP` proxy for consistent, trusted IPs
  * Create a browser profile with an existing authenticated session
  * Slow down requests by adding explicit waits in your prompt
</Accordion>

<Accordion title="How do I persist cookies across runs?">
  Use browser profiles:

  1. Create a browser profile in Settings > Browser Profiles
  2. Log in manually or via an agent
  3. Reference the `browser_profile_id` in subsequent runs

  The profile preserves cookies, localStorage, and session state across runs.
</Accordion>

<Accordion title="Can I connect Skyvern to my local browser?">
  Yes, for self-hosted installations:

  ```bash theme={null}
  skyvern init  # Choose "connect to existing Chrome" option
  skyvern run server
  ```

  This connects to Chrome running on your machine, useful for debugging or accessing internal tools.
</Accordion>

<Accordion title="Why am I getting a 504 timeout when creating browser sessions?">
  This usually indicates high load or network issues:

  * Wait a few seconds and retry
  * Check your rate limits
  * For self-hosted: verify your infrastructure has sufficient resources

  If persistent, contact support with your run IDs.
</Accordion>

***

## Self-Hosting & Deployment

<Accordion title="What are the requirements for self-hosting Skyvern?">
  * Python 3.11, 3.12, or 3.13
  * PostgreSQL database
  * An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Ollama)
  * Docker (optional, for containerized deployment)

  Run `skyvern init` for an interactive setup wizard. See the [Quickstart](/developers/getting-started/quickstart) for full instructions.
</Accordion>

<Accordion title="How do I update my self-hosted Skyvern instance?">
  ```bash theme={null}
  pip install --upgrade skyvern
  alembic upgrade head  # Run database migrations
  skyvern run server    # Restart the server
  ```

  For Docker deployments, pull the latest image and restart your containers.
</Accordion>

<Accordion title="How do I configure a custom LLM provider?">
  Set these environment variables:

  ```bash theme={null}
  ENABLE_OPENAI=true  # or ENABLE_ANTHROPIC, ENABLE_AZURE, etc.
  OPENAI_API_KEY=sk-...
  LLM_KEY=OPENAI_GPT5_5
  ```

  Skyvern supports OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, and Ollama. Run `skyvern init llm` for guided configuration.
</Accordion>

***

## Billing & Pricing

<Accordion title="How is pricing calculated?">
  Pricing depends on your plan:

  * **Pay-as-you-go**: Charged per step or per task completion
  * **Enterprise**: Custom pricing based on volume

  View your usage and billing at [Settings > Billing](https://app.skyvern.com/billing).
</Accordion>

<Accordion title="Why does it say insufficient balance when I have credit?">
  Credits may be reserved for in-progress runs. Check:

  1. Active runs that haven't completed yet
  2. Failed runs that consumed partial credit
  3. Pending charges that haven't settled

  Wait for active runs to complete, then check your balance again.
</Accordion>

<Accordion title="How do I get invoices for my payments?">
  Go to [Settings > Billing](https://app.skyvern.com/billing) to download invoices. For custom invoice requirements (company name, VAT, etc.), contact support.
</Accordion>

***

## Still have questions?

<CardGroup cols={2}>
  <Card title="Troubleshooting Guide" icon="wrench" href="/developers/debugging/troubleshooting-guide">
    Step-by-step debugging for failed runs
  </Card>

  <Card title="Contact Support" icon="headset" href="https://app.skyvern.com">
    Chat with us via the support widget
  </Card>
</CardGroup>