Scroll page

​

Endpoint

POST /tabs/:tabId/scroll

​

Authentication

​

Path parameters

​

Body parameters

​

Response

​

Behavior

• Scrolling is performed using mouse wheel events
• After scrolling, waits 300ms for scroll animations and lazy-loaded content
• Does not invalidate element references (use /snapshot if new content appears)
• Scrolling beyond page bounds is handled gracefully (no error)

​

Default scroll amounts

• Default: 500 pixels (approximately half a viewport on typical screens)

• Small: 200-300 pixels (peek at more content)
• Medium: 500 pixels (default, half viewport)
• Large: 1000+ pixels (jump to new section)
• Full page: Use viewport height (typically 720-1080)

​

Error codes

• 400 - Missing required parameter (userId)
• 404 - Tab not found
• 500 - Internal server error

​

Examples

​

Scroll down (default)

curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1"
  }'

{
  "ok": true
}

​

Scroll down with custom amount

curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "direction": "down",
    "amount": 1000
  }'

​

Scroll up

curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "direction": "up",
    "amount": 500
  }'

​

Scroll horizontally

curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "direction": "right",
    "amount": 300
  }'

​

Use cases

​

Load lazy content

# 1. Scroll to trigger lazy load
curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -d '{"userId": "agent1", "direction": "down", "amount": 1000}'

# 2. Get new snapshot with loaded content
curl "http://localhost:9377/tabs/abc123/snapshot?userId=agent1"

​

Navigate paginated content

for i in {1..5}; do
  curl -X POST http://localhost:9377/tabs/abc123/scroll \
    -d '{"userId": "agent1", "direction": "down", "amount": 800}'
  sleep 1
done

​

Scroll to top

curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "direction": "up",
    "amount": 99999
  }'

​

Scroll to bottom

curl -X POST http://localhost:9377/tabs/abc123/scroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "direction": "down",
    "amount": 99999
  }'

​

Best practices

1. Wait after scrolling: The 300ms built-in delay may not be enough for heavy pages - consider waiting 1-2s before snapshot
2. Scroll incrementally: Multiple small scrolls (500px) are better than one large scroll for triggering lazy loaders
3. Check for new content: Compare refsCount before/after scrolling to detect loaded content
4. Avoid excessive scrolling: Scrolling beyond page bounds is safe but wastes time

​

Related endpoints

• GET /tabs/:tabId/snapshot - Get page snapshot after scrolling to access new elements
• GET /tabs/:tabId/links - Extract links without scrolling (may miss lazy-loaded links)