> For the complete documentation index, see [llms.txt](https://gaffa.dev/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gaffa.dev/docs/api-reference/post-v1-browser-requests.md).

# POST v1/browser/requests

{% hint style="info" %}
For more information on browser requests, [see here](/docs/features/browser-requests.md).
{% endhint %}

The following endpoint creates a browser request and either runs it synchronously or returns immediately with an ID so you can check its status later.

## Create a new browser request

> This endpoint loads the required URL in our browser and then performs the selected actions.

```json
{"openapi":"3.0.1","info":{"title":"Gaffa API Open API Definition","version":"1.0.0"},"servers":[{"url":"https://api.gaffa.dev"}],"security":[{"API Key":[]}],"components":{"securitySchemes":{"API Key":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"browserRequestInput_object":{"type":"object","properties":{"proxy_location":{"type":"string","description":"The location of the proxy server that your request will be routed through, null means no proxy is used","default":"null","nullable":true},"url":{"type":"string","description":"The url you want our browsers to visit on your behalf"},"async":{"type":"boolean","description":"Whether the request should be processed asynchronously. Synchronous requests always return either the result or a timeout error, and their maximum time_limit is the lower of your plan's limit and 120000ms: 60000ms on Pay As You Go and Starter, 120000ms on Startup and Growth.","default":false},"max_cache_age":{"type":"integer","description":"The maximum age of a cached result in seconds. 0 means the cache will never be used","format":"int32","default":0,"nullable":true},"settings":{"$ref":"#/components/schemas/browserRequestSettings_object"}}},"browserRequestSettings_object":{"type":"object","properties":{"record_request":{"type":"boolean","description":"Record a video of this request","default":false,"nullable":true},"actions":{"type":"array","items":{"$ref":"#/components/schemas/dictionary_object"},"description":"A list of the functions you want to perform on the web page"},"time_limit":{"type":"integer","description":"Cap the maximum time the request should take to complete, in milliseconds (default: 60000). The maximum depends on your plan: async requests allow 60000ms on Pay As You Go and Starter, 120000ms on Startup and 300000ms on Growth, and synchronous requests are further capped at 120000ms. Requests above the limit are rejected with a 400.","format":"int32","default":60000,"nullable":true},"max_media_bandwidth":{"type":"integer","description":"Cap the maximum bandwidth to use for media downloads, in MB","format":"int32","nullable":true},"output":{"$ref":"#/components/schemas/browserRequestOutput"},"block_ads":{"type":"boolean","description":"Enable ad blocking for this request","default":false,"nullable":true},"block_non_essential_assets":{"type":"boolean","description":"Block fonts and third-party stylesheets to reduce bandwidth, without blocking scripts or API calls a JS SPA needs to function","default":false,"nullable":true},"log_redirects":{"type":"boolean","description":"Capture and return redirect chain URLs for the request","default":false,"nullable":true},"session_continuation":{"$ref":"#/components/schemas/sessionContinuationSettings"}},"description":"The actions and outputs you want to be executed"},"dictionary_object":{"type":"object","additionalProperties":{"type":"object"}},"browserRequestOutput":{"type":"object","properties":{"webhook_url":{"type":"string","description":"Webhook URL to receive results","nullable":true}},"description":"Output configuration for the request (restricted to integration requests)","nullable":true},"sessionContinuationSettings":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable session continuation to receive proxy credentials for continued use after the request","default":false,"nullable":true},"duration_minutes":{"type":"integer","description":"Duration in minutes for the continued session (default: 30)","format":"int32","default":30},"vendor":{"type":"string","description":"Preferred proxy vendor","nullable":true}},"nullable":true},"response_browserRequestResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/browserRequestResponse"},"error":{"$ref":"#/components/schemas/apiErrorResponse"}}},"browserRequestResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the browser request","nullable":true},"url":{"type":"string","description":"URL of the request","nullable":true},"proxy_location":{"type":"string","description":"The proxy location of the request.","nullable":true},"state":{"type":"string","description":"The status of the request","nullable":true},"credit_usage":{"type":"integer","description":"The number of tokens used by the request","format":"int32","nullable":true},"error":{"type":"string","description":"The name of the error type","nullable":true},"error_reason":{"type":"string","description":"More detail about the error","nullable":true},"actual_url":{"type":"string","description":"The actual URL captured, after any redirects.","nullable":true},"http_status_code":{"type":"integer","description":"The http status code for the request.","format":"int32","nullable":true},"from_cache":{"type":"boolean","description":"If this request was served from the cached","nullable":true},"data_deleted":{"type":"boolean","description":"Whether the stored data for this request has been deleted by data retention. When true the request is returned as metadata only — its actions, video and redirects are no longer available, and it is never served from cache.","nullable":true},"started_at":{"type":"string","description":"The time in UTC when the request started.","format":"date-time","nullable":true},"completed_at":{"type":"string","description":"The time in UTC when the request finished.","format":"date-time","nullable":true},"running_time":{"type":"string","description":"The running time of the request","format":"timespan","nullable":true},"page_load_time":{"type":"string","description":"How long did the page take to fully render.","format":"timespan","nullable":true},"actions":{"type":"array","items":{"$ref":"#/components/schemas/browerRequestActionResponse"},"description":"Actions carried out and their results","nullable":true},"redirects":{"type":"array","items":{"type":"string"},"description":"Redirect chain URLs captured during navigation","nullable":true},"video":{"type":"string","description":"Video url","nullable":true},"session_continuation":{"$ref":"#/components/schemas/sessionContinuationResponse"}},"description":"The result, if this response represents a success.","nullable":true},"browerRequestActionResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the action","nullable":true},"type":{"type":"string","description":"Name of the action","nullable":true},"custom_id":{"type":"string","description":"Custom ID of the action","nullable":true},"timestamp":{"type":"string","description":"Time the action was initiated","format":"date-time"},"output":{"type":"object","description":"Ouput of the action, if any","nullable":true},"reference":{"type":"string","description":"Reference file for the action, if any","nullable":true},"iterations":{"type":"integer","description":"Number of iterations completed for loop actions","format":"int32","nullable":true},"actions":{"type":"array","items":{"$ref":"#/components/schemas/browerRequestActionResponse"},"description":"Nested actions executed within loop actions","nullable":true},"error":{"type":"string","description":"Error message, if any","nullable":true}}},"sessionContinuationResponse":{"type":"object","properties":{"session_id":{"type":"string","nullable":true},"host":{"type":"string","nullable":true},"port":{"type":"integer","format":"int32","nullable":true},"username":{"type":"string","nullable":true},"password":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"location":{"type":"string","nullable":true},"assigned_ip":{"type":"string","nullable":true}},"nullable":true},"apiErrorResponse":{"type":"object","properties":{"type":{"type":"string","description":"The type of object this is concerning","nullable":true},"id":{"type":"string","description":"The id of the item concerned.","nullable":true},"code":{"type":"string","description":"Error code.","nullable":true},"message":{"type":"string","description":"Error description.","nullable":true}},"description":"The error, if this response represents a failure.","nullable":true}}},"paths":{"/v1/browser/requests":{"post":{"tags":["Browser Requests"],"summary":"Create a new browser request","description":"This endpoint loads the required URL in our browser and then performs the selected actions.","operationId":"createBrowserRequest","requestBody":{"description":"Browser request input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/browserRequestInput_object"}}},"required":true},"responses":{"200":{"description":"The browser request response detailing the state and output of the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/response_browserRequestResponse"}}}},"400":{"description":"The request is invalid, e.g. a required action parameter is missing (missing_action_param), the url or actions are missing, an action or its parameters are invalid, or a synchronous request's time_limit is above its limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/response_browserRequestResponse"}}}},"408":{"description":"The browser request timed out - an example error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/response_browserRequestResponse"}}}}}}}}}
```


---

# 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://gaffa.dev/docs/api-reference/post-v1-browser-requests.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.