Instances API

Create and manage browser instances

Overview

Instances are running Chrome browser processes managed by PinchTab. Each instance:

• Runs an independent Chrome process
• Uses a specific profile (user data directory)
• Can be headed (visible window) or headless (background)
• Manages its own tabs
• Has isolated cookies, history, and state

List Instances

cURL

curl http://localhost:9867/instances | jq .

Response

[
  {
    "id": "inst_0a89a5bb",
    "profileId": "prof_278be873",
    "profileName": "Pinchtab org",
    "port": "9868",
    "headless": true,
    "status": "running",
    "startTime": "2026-03-01T05:21:38.274Z"
  }
]

Response Fields

id · string · required

Instance ID (format: inst_XXXXXXXX)

profileId · string · required

Profile ID used by this instance

profileName · string · required

Human-readable profile name

port · string · required

Port number (as string)

headless · boolean · required

true for headless mode, false for headed (visible window)

status · string · required

Instance status: starting, running, stopping, error

startTime · string · required

ISO 8601 timestamp when instance started

error · string

Error message if status is error

---

Start Instance

Start a new Chrome instance with optional profile, mode, and port.

POST /instances/start

cURL (Minimal)

# Auto-allocates port, uses temporary profile, headless mode
curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body

profileId · string

Profile ID or name. If omitted, creates a temporary profile.

mode · string · default: "headless"

Browser mode: "headed" (visible window) or "headless" (background)

port · string

Port number. If omitted, auto-allocated from available ports.

Response (201 Created)

{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "Pinchtab org",
  "port": "9868",
  "headless": false,
  "status": "starting",
  "startTime": "2026-03-01T05:21:38.274Z"
}

Status transitions from starting → running when Chrome is fully initialized.

---

Get Instance Details

GET /instances/{id}

curl http://localhost:9867/instances/inst_ea2e747f | jq .

Response (200 OK)

{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "Pinchtab org",
  "port": "9868",
  "headless": false,
  "status": "running",
  "startTime": "2026-03-01T05:21:38.274Z"
}

---

Stop Instance

Gracefully shut down a running instance.

POST /instances/{id}/stop

curl -X POST http://localhost:9867/instances/inst_ea2e747f/stop

Response (200 OK)

{
  "id": "inst_ea2e747f",
  "status": "stopped"
}

Stopping an instance closes all its tabs and terminates the Chrome process. The profile is preserved.

---

Get Instance Logs

Retrieve logs for debugging instance startup issues.

GET /instances/{id}/logs

curl http://localhost:9867/instances/inst_ea2e747f/logs

Response (200 OK - Plain Text)

2026-03-01 05:21:38 INFO starting instance process id=inst_ea2e747f profile=Pinchtab org port=9868
2026-03-01 05:21:40 INFO instance ready id=inst_ea2e747f

Logs are returned as plain text, not JSON.

---

Complete Workflow Example

#!/bin/bash

BASE="http://localhost:9867"

# 1. Start instance (headed mode, auto port)
echo "Starting instance..."
INST=$(curl -s -X POST $BASE/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headed"}' | jq -r '.id')

echo "Instance: $INST"

# 2. Wait for instance to be ready
sleep 2

# 3. Check status
STATUS=$(curl -s $BASE/instances/$INST | jq -r '.status')
echo "Status: $STATUS"

# 4. Get logs
echo -e "\nInstance logs:"
curl -s $BASE/instances/$INST/logs | tail -5

# 5. List all instances
echo -e "\nAll instances:"
curl -s $BASE/instances | jq '.[] | {id, port, status}'

# 6. Stop instance
echo -e "\nStopping instance..."
curl -s -X POST $BASE/instances/$INST/stop | jq .

echo "Done"

---

Instance Status Values

Status	Description
starting	Instance process spawning, Chrome initializing
running	Instance healthy and ready to accept commands
error	Instance failed to start
stopping	Instance is shutting down
stopped	Instance has been terminated

---

Error Handling

Profile Not Found (404)

curl -X POST http://localhost:9867/instances/start \
  -d '{"profileId":"nonexistent"}'

Response:

{
  "error": "profile \"nonexistent\" not found",
  "statusCode": 404
}

Port Already in Use (409)

curl -X POST http://localhost:9867/instances/start \
  -d '{"port":"9867"}'

Response:

{
  "error": "port 9867 already in use",
  "statusCode": 409
}

Instance Not Found (404)

curl http://localhost:9867/instances/nonexistent/logs

Response:

{
  "error": "instance not found",
  "statusCode": 404
}

---

Best Practices

Port Management

# Let PinchTab auto-allocate ports (recommended)
curl -X POST $BASE/instances/start -d '{}'

# Or manually specify if needed
curl -X POST $BASE/instances/start -d '{"port":"9999"}'

Profile Selection

Use named profiles to preserve state across instance restarts:

# With profile (state persists)
curl -X POST $BASE/instances/start \
  -d '{"profileId":"my-profile"}'

# Temporary profile (good for isolated testing)
curl -X POST $BASE/instances/start -d '{}'

Cleanup

Always stop instances when done:

# Stop specific instance
curl -X POST $BASE/instances/$INST_ID/stop

# Stop all instances (shell script)
for id in $(curl -s $BASE/instances | jq -r '.[].id'); do
  curl -s -X POST $BASE/instances/$id/stop
done

---

Python Integration Example

import requests
import time

BASE = "http://localhost:9867"

class PinchTabInstance:
    def __init__(self, profile_id=None, mode="headless"):
        resp = requests.post(f"{BASE}/instances/start", json={
            "profileId": profile_id,
            "mode": mode
        })
        data = resp.json()
        self.id = data["id"]
        self.port = data["port"]
        
        # Wait for ready
        time.sleep(2)
    
    def status(self):
        resp = requests.get(f"{BASE}/instances/{self.id}")
        return resp.json()["status"]
    
    def logs(self):
        resp = requests.get(f"{BASE}/instances/{self.id}/logs")
        return resp.text
    
    def stop(self):
        requests.post(f"{BASE}/instances/{self.id}/stop")

# Usage
instance = PinchTabInstance(mode="headed")
print(f"Instance: {instance.id}")
print(f"Status: {instance.status()}")
instance.stop()

---

Next Steps

Profiles API

Manage browser profiles for instances

Tabs API

List and manage tabs within instances

Navigation

Navigate tabs to URLs

Actions API

Automate browser interactions