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

# Emulate a device

> Override viewport, location, timezone, locale, and user agent per tab

Make a tab look like a different device or place: a phone viewport, a New York timezone, a French locale. Overrides are field-scoped — send only the keys you want to change — remembered per tab, and re-applied if the agent re-attaches to that tab.

CLI and cURL examples use `$RT` and browser `b1` ([Sessions](https://docs.gravixlayer.ai/documentation/agentruntime/browser-use/browser.md)).

## Emulate a phone in one call

`emulate` takes any of `viewport` (`{width, height, scale}`), `geolocation` (`{latitude, longitude, accuracy}`), `timezone` (IANA name), `locale` (also sets `Accept-Language`), `user_agent`, `mobile`, `touch`, and `color_scheme` (`light`/`dark`). Pass `target_id` to aim at one tab or `context_id` at a whole context; with neither, the override applies browser-wide.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()  # reads GRAVIXLAYER_API_KEY
sandbox = client.runtime.create(template="browser-small")
bid = sandbox.browser.open(url="https://example.com")["browser_id"]
tab = sandbox.browser.targets(bid)["target_id"]

sandbox.browser.emulate(
    bid,
    target_id=tab,
    viewport={"width": 390, "height": 844, "scale": 3},
    geolocation={"latitude": 40.71, "longitude": -74.0, "accuracy": 50},
    timezone="America/New_York",
    locale="en-US",
    user_agent="Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    touch=True,
    color_scheme="dark",
)

snap = sandbox.browser.snapshot(bid)
print(snap["viewport"])  # {'width': 390, 'height': 844}
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'browser-small' });
const bid = (await sandbox.browser.open({ url: 'https://example.com' })).browserId;
const tab = (await sandbox.browser.targets(bid)).targetId;

await sandbox.browser.emulate(bid, {
  targetId: tab,
  viewport: { width: 390, height: 844, scale: 3 },
  geolocation: { latitude: 40.71, longitude: -74.0, accuracy: 50 },
  timezone: 'America/New_York',
  locale: 'en-US',
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)',
  touch: true,
  colorScheme: 'dark',
});

const snap = await sandbox.browser.snapshot(bid);
console.log(snap.viewport); // { width: 390, height: 844 }
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime browser emulate "$RT" --browser b1 --tab t1 \
  --viewport '{"width":390,"height":844,"scale":3}' \
  --geolocation '{"latitude":40.71,"longitude":-74.0,"accuracy":50}' \
  --timezone America/New_York --locale en-US \
  --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)" \
  --mobile true --touch true --color-scheme dark
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/browser/b1/emulate" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "t1",
    "width": 390,
    "height": 844,
    "device_scale_factor": 3,
    "mobile": true,
    "geolocation_lat": 40.71,
    "geolocation_lon": -74.0,
    "geolocation_accuracy": 50,
    "timezone_id": "America/New_York",
    "locale": "en-US",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "touch": true,
    "color_scheme": "dark"
  }'
```

## Clear every override

`clear` drops all overrides on the scope in one call and returns the tab to its real environment. Emulation otherwise survives navigations on the same tab and does not leak to other tabs or contexts.

```python Python theme={null}
sandbox.browser.emulate(bid, target_id=tab, clear=True)
```

```typescript TypeScript theme={null}
await sandbox.browser.emulate(bid, { targetId: tab, clear: true });
```

```bash CLI theme={null}
gravixlayer runtime browser emulate "$RT" --browser b1 --tab t1 --clear
```

```bash cURL theme={null}
curl -sS -X POST "$API/agents/runtime/$RT/browser/b1/emulate" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "t1", "clear": true}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.