> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/web-api/playground.md).

# Web API Playground

Learn how to use the Web API Playground to build and test Search and Scrape requests, preview results, and export ready-to-use code.

[**Web API Playground**](https://dashboard.oxylabs.io/playground/web-api/search) is an interactive tool available in the Oxylabs dashboard. It allows you to build and test Web API requests without writing code.

With Web API Playground, you can run `/search` and `/scrape` requests side by side, adjust request parameters, switch output formats, preview results, and copy ready-to-use code in language of your choice. 

It's designed for quick prototyping, exploring what the API returns for a target, and verifying a request before adding it to your project.

### Who can use it?

Web API Playground is available to all Oxylabs dashboard users with access to Web API.

* **New users** can start with a $5 welcome credit.
* **Existing customers** can use the Playground alongside their regular API integrations as a testing and prototyping environment.

{% hint style="info" %}
Web API Playground is intended for **testing and exploration** only. For high-volume or automated workflows, call the Web API endpoints directly from your code and use the delivery modes built for large volumes.
{% endhint %}

## How to use it

{% stepper %}
{% step %}

### Access Web API Playground

Log in to the [Oxylabs dashboard](https://dashboard.oxylabs.io/) and open your Web API product instance.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FrHJvPSmZfrSOLJphS6tZ%2FScreenshot%202026-10-20%20at%2016.45.44.png?alt=media&amp;token=eed640cc-f571-4453-adbd-22ea0348655c" alt=""><figcaption></figcaption></figure>

The Playground is located in the center of your Web API product instance Overview.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2F4AoAa4S2z2VY09X8iK0j%2FScreenshot%202026-10-20%20at%2016.48.20.png?alt=media&amp;token=70ad1f9a-4a1a-4da5-ac99-ab0af440736c" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Select an endpoint

Choose `/search` to discover fresh, ranked sources for a query, or `/scrape` to retrieve clean, structured data from a known URL.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FsDA7DFjttru2iSCV2Krz%2FScreenshot%202026-10-20%20at%2016.58.42.png?alt=media&amp;token=a988e1f3-cbc6-4ba4-a4de-857e5787398e" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Enter the details

Depending on your chosen Web API Playground mode, check the corresponding tab below:

{% tabs %}
{% tab title="Search" %}
For `/search`, enter the keyword or phrase you want to search for.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fft12kN4l2j5sjndYBF0M%2FScreenshot%202026-10-20%20at%2017.34.47.png?alt=media&amp;token=055c3b47-e47b-455b-b617-0966f48c6343" alt="" width="440"><figcaption></figcaption></figure>

Then, adjust the request for your use case by clicking the **Options** button:

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Ft2b3BkSILoi0NvlGmNXT%2FScreenshot%202026-10-20%20at%2017.40.45.png?alt=media&amp;token=2b2573c5-b0f6-4fe9-93a8-6343d71d153a" alt="" width="446"><figcaption></figcaption></figure>

* **Number of results (**`max_results`**):**  Number of organic search items to return Default: `10`, maximum: `20`.
* **Target localization (**`location`**):** Searchable dropdown accepting 2-letter ISO country codes (e.g., `US`, `DE`, `GB`) to localize Web API search results.
  {% endtab %}

{% tab title="Scrape" %}
For `/scrape`, enter the target page URL for scraping.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2F8Uw3Otpk7u3H8ud3GGOq%2FScreenshot%202026-10-20%20at%2017.36.30.png?alt=media&amp;token=03374f56-502e-46cd-af8b-22e4667bf092" alt="" width="444"><figcaption></figcaption></figure>

Then, adjust the request for your use case by clicking the **Options** button:

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fc3ktRkEIpVMP4bk0UQNg%2FScreenshot%202026-10-20%20at%2017.53.52.png?alt=media&amp;token=8cd2aa18-3f17-4f02-886d-d6d576f83227" alt="" width="442"><figcaption></figcaption></figure>

<table data-header-hidden><thead><tr><th width="195"></th><th></th></tr></thead><tbody><tr><td><strong>Location (</strong><code>location</code><strong>)</strong></td><td>Country-level IP geo-targeting for localization and geo-fenced page access.</td></tr><tr><td><strong>Device (</strong><code>device</code><strong>)</strong></td><td>Configures request client headers and viewport emulation as <code>Desktop</code> (default) or <code>Mobile</code>.</td></tr><tr><td><strong>JS rendering (</strong><code>run_js</code><strong>)</strong></td><td>Enables headless browser JavaScript execution for client-side rendering.</td></tr></tbody></table>

{% hint style="warning" %}
**Note:** JavaScript rendering adds additional credit usage for `/scrape` endpoint requests.
{% endhint %}

Finally, click the **Output** button to configure delivery formats. Multiple output formats can be chosen:

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FX8jhDBpZZZNqd9le8o6K%2FScreenshot%202026-10-20%20at%2018.03.38.png?alt=media&amp;token=79eff283-cd33-4409-b913-cc88596e265c" alt=""><figcaption></figcaption></figure>

<table data-header-hidden><thead><tr><th width="126"></th><th></th></tr></thead><tbody><tr><td>HTML</td><td>Returns raw unparsed or rendered DOM HTML (default)</td></tr><tr><td>Markdown</td><td>Converts page DOM into clean, LLM-ready Markdown, discarding boilerplate script/style tags, LLM-friendly output option.</td></tr><tr><td>JSON</td><td>Returns structured programmatic data. (requires either <code>schema</code> or <code>prompt</code>-based extraction rules. Learn more about both extraction modes in <a href="/products/web-api/scrape/ai-parsing.md">AI Parsing</a> page.)</td></tr><tr><td>Screenshot</td><td>Captures a full visual page render. Requires JS rendering, costs extra.</td></tr></tbody></table>

Selecting multiple options appends each value to the payload's `output` array (e.g. `"output": ["html", "md"]`).
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Run the request

Submit your request by clicking the **arrow button** and preview the returned data in the **Output** section below.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fg2blsFgN3IDDPiZvwQAi%2FScreenshot%202026-10-20%20at%2018.19.09.png?alt=media&amp;token=938fd0e0-2eff-4c02-9ad2-1b6c83d4f7ed" alt=""><figcaption></figcaption></figure>

From here, you can preview the results, evaluate your response speed, inspect or download the result output in your chosen output formats.
{% endstep %}

{% step %}

### Export

If you're happy with the results, switch to the **Request** tab, where you can copy the generated code in your preferred language and use it in your scripts or applications.

If you wish to integrate Web API into your AI agent or coding assistant, you can also choose the **Copy to agents** option which integrates Web API with your agent in a single prompt.

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FARyOuDiUswjxOeabPTdv%2FScreenshot%202026-10-20%20at%2018.30.12.png?alt=media&amp;token=8421a154-5058-4777-aa83-c908d2dbe288" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The exported code authenticates with your API key. Keep it server-side and never commit it to source control. See [Authentication](/products/web-api/authentication.md).&#x20;
{% endhint %}
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/web-api/playground.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.