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

# Mouse Click

> Simulate a mouse click on the session's active page, by coordinates or by CSS selector.

## Overview

The `/browser/sessions/{id}/mouse/click` endpoint dispatches a mouse click against the currently active page inside a browser session. It supports two modes:

* **Coordinates** — click at `(x, y)` in viewport CSS pixels.
* **Selector** — click the center of an element matched by a CSS selector. Waits for the element to be visible.

The two modes are mutually exclusive. Pass either `(x, y)` **or** `selector`, never both.

## Path Parameters

<ParamField path="id" type="string" required={true}>
  Browser session ID (UUID). Create via `POST /browser/sessions`.
</ParamField>

## Body

<ParamField body="x" type="integer">
  X coordinate in viewport CSS pixels. Required together with `y` when `selector` is omitted.
</ParamField>

<ParamField body="y" type="integer">
  Y coordinate in viewport CSS pixels. Required together with `x` when `selector` is omitted.
</ParamField>

<ParamField body="selector" type="string">
  CSS selector of the element to click. Mutually exclusive with `x`/`y`. Clicks the center of the element's bounding box.
</ParamField>

<ParamField body="timeout" type="integer" default="5000">
  How long to wait (ms) for the selector to become visible. Ignored when using coordinates.
</ParamField>

<ParamField body="index" type="integer" default="0">
  Which match to click when the selector resolves to multiple elements (0-based).
</ParamField>

<ParamField body="button" type="string" default="left">
  Mouse button to press. One of `left`, `right`, `middle`, `back`, `forward`. The `back` and `forward` buttons map to the side buttons used for browser navigation on some sites.
</ParamField>

<ParamField body="holdKeys" type="string[]">
  Modifier keys held for the duration of the click. Each value must be one of `Shift`, `Control`, `Alt`, `Meta`.
</ParamField>

<ParamField body="numClicks" type="integer" default="1">
  Number of clicks to issue at the same point. Capped at 10.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL (coordinates) theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/0f2b1f6a-88ac-4d25-bc58-67a6f4b4a001/mouse/click" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "x": 120,
      "y": 240,
      "button": "left"
    }'
  ```

  ```bash cURL (selector) theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/0f2b1f6a-88ac-4d25-bc58-67a6f4b4a001/mouse/click" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "selector": "button[type=submit]",
      "holdKeys": ["Shift"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.scrapengine.io/api/v1/browser/sessions/0f2b1f6a-88ac-4d25-bc58-67a6f4b4a001/mouse/click",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        selector: "button[type=submit]",
        numClicks: 2,
      }),
    },
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.scrapengine.io/api/v1/browser/sessions/0f2b1f6a-88ac-4d25-bc58-67a6f4b4a001/mouse/click"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
  }
  payload = {
      "selector": "button[type=submit]",
      "numClicks": 2,
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  ```
</CodeGroup>

## Response

### Success Response (200)

<ResponseField name="x" type="integer">
  X coordinate actually clicked (in viewport CSS pixels). For selector mode, this is the center of the resolved element.
</ResponseField>

<ResponseField name="y" type="integer">
  Y coordinate actually clicked (in viewport CSS pixels).
</ResponseField>

**Example Response:**

```json theme={null}
{
  "x": 120,
  "y": 240
}
```

### Error Responses

| Status | Description                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid body — both coordinate and selector modes supplied, selector didn't match, unknown button/modifier, or numClicks out of range. |
| `401`  | Unauthorized — invalid or missing API key.                                                                                             |
| `404`  | Session not found or not owned by the caller.                                                                                          |
| `503`  | The browser session is temporarily unreachable.                                                                                        |

## Notes

* **Coordinate system**: coordinates are viewport-relative in CSS pixels. On HiDPI pages, they do not need to be scaled by `devicePixelRatio` — the browser handles that internally.
* **Selector mode**: the endpoint waits up to `timeout` ms for the first match to become visible, then clicks the center of its bounding box. Use `index` to target the Nth match.
* **Modifiers**: `holdKeys` are held for the full duration of every click in a multi-click sequence.