# 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 can be maximum 60 seconds long.","default":true},"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)","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},"block_ads":{"type":"boolean","description":"Enable ad blocking for this request","default":false,"nullable":true}},"description":"The actions and outputs you want to be executed"},"dictionary_object":{"type":"object","additionalProperties":{"type":"object"}},"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 credits 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"},"from_cache":{"type":"boolean","description":"If this request was served from the cached","nullable":true},"started_at":{"type":"string","description":"The time in UTC when the request started.","format":"date-time"},"completed_at":{"type":"string","description":"The time in UTC when the request finished.","format":"date-time"},"running_time":{"type":"string","description":"The running time of the request","format":"timespan"},"page_load_time":{"type":"string","description":"How long did the page take to fully render.","format":"timespan"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/browerRequestActionResponse"},"description":"Actions carried out and their results","nullable":true},"video":{"type":"string","description":"Video url","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"},"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}}},"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}}}}},"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/browserRequestResponse"}}}},"408":{"description":"The browser request timed out - an example error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/apiErrorResponse"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gaffa.dev/docs/api-reference/post-v1-browser-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.