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

# Pinch by Description

> Pinch/zoom on an element using natural language description

Pinch, zoom, or rotate on an element described in natural language. Uses vision AI to find the element and perform the gesture.

## Request

```bash theme={null}
curl -X POST https://api.tapkit.ai/v1/phones/{phone_id}/pinch/select \
  -H "X-API-Key: joot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"selector": "the map", "action": "pinch_out", "duration_ms": 1000}'
```

### Path Parameters

| Parameter  | Type     | Description          |
| ---------- | -------- | -------------------- |
| `phone_id` | `string` | The phone identifier |

### Query Parameters

| Parameter | Type      | Default | Description                    |
| --------- | --------- | ------- | ------------------------------ |
| `async`   | `boolean` | `false` | Return immediately with job ID |

### Request Body

```json theme={null}
{
  "selector": "the map",
  "action": "pinch_out",
  "duration_ms": 1000
}
```

| Field         | Type      | Default  | Description                                                   |
| ------------- | --------- | -------- | ------------------------------------------------------------- |
| `selector`    | `string`  | required | Natural language description of the element                   |
| `action`      | `string`  | required | `"pinch_in"`, `"pinch_out"`, `"rotate_cw"`, or `"rotate_ccw"` |
| `duration_ms` | `integer` | `1000`   | Gesture duration in milliseconds                              |

### Actions

| Action       | Effect                      |
| ------------ | --------------------------- |
| `pinch_out`  | Zoom in (fingers apart)     |
| `pinch_in`   | Zoom out (fingers together) |
| `rotate_cw`  | Rotate clockwise            |
| `rotate_ccw` | Rotate counter-clockwise    |

## Response

### Synchronous

```json theme={null}
{
  "id": "job_abc123",
  "status": "completed",
  "result": {},
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:02Z"
}
```

### Asynchronous

```json theme={null}
{
  "job_id": "job_abc123"
}
```

## Examples

### Zoom In on a Map

```bash theme={null}
curl -X POST https://api.tapkit.ai/v1/phones/abc123/pinch/select \
  -H "X-API-Key: joot_..." \
  -H "Content-Type: application/json" \
  -d '{"selector": "the map view", "action": "pinch_out", "duration_ms": 1000}'
```

### SDK Usage

The Python SDK provides this through the `pinch()` method with a string argument:

```python theme={null}
phone.pinch("the map", "pinch_out")      # Zoom in
phone.pinch("the photo", "pinch_in", duration_ms=1500)  # Zoom out
phone.pinch("the image", "rotate_cw")    # Rotate clockwise
```

## Related Endpoints

* [Pinch](/api-reference/phones/pinch) - Pinch at specific coordinates
* [Double Tap](/api-reference/phones/double-tap) - Alternative zoom method