File size: 4,693 Bytes
6a7089a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | # Profiles
Profiles are browser user data directories. They hold cookies, local storage, history, and other durable browser state.
In PinchTab:
- profiles exist even when no instance is running
- one profile can have at most one active managed instance at a time
- profile IDs and names are both useful, but some endpoints require the profile ID specifically
## List Profiles
```bash
curl http://localhost:9867/profiles
# CLI Alternative
pinchtab profiles
# Response
[
{
"id": "prof_278be873",
"name": "work",
"created": "2026-02-27T20:37:13.599055326Z",
"diskUsage": 534952089,
"sizeMB": 510.17,
"running": false,
"source": "created",
"useWhen": "Use for work accounts",
"description": ""
}
]
```
Notes:
- `GET /profiles` excludes temporary auto-generated instance profiles by default
- use `GET /profiles?all=true` to include temporary profiles
- `pinchtab profiles` exists, but the HTTP API is the more reliable source of truth for structured output
## Get One Profile
```bash
curl http://localhost:9867/profiles/prof_278be873
# Response
{
"id": "prof_278be873",
"name": "work",
"path": "/path/to/profiles/work",
"pathExists": true,
"created": "2026-02-27T20:37:13.599055326Z",
"diskUsage": 534952089,
"sizeMB": 510.17,
"source": "created",
"chromeProfileName": "Your Chrome",
"accountEmail": "admin@example.com",
"accountName": "Luigi",
"hasAccount": true,
"useWhen": "Use for work accounts",
"description": ""
}
```
`GET /profiles/{id}` accepts either the profile ID or the profile name.
## Create A Profile
```bash
curl -X POST http://localhost:9867/profiles \
-H "Content-Type: application/json" \
-d '{"name":"scraping-profile","description":"Used for scraping","useWhen":"Use for ecommerce scraping"}'
# Response
{
"status": "created",
"id": "prof_0f32ae81",
"name": "scraping-profile"
}
```
Notes:
- there is no `pinchtab profile create` CLI command
- both `POST /profiles` and `POST /profiles/create` work for creating profiles
## Update A Profile
```bash
curl -X PATCH http://localhost:9867/profiles/prof_278be873 \
-H "Content-Type: application/json" \
-d '{"description":"Updated description","useWhen":"Updated usage note"}'
# Response
{
"status": "updated",
"id": "prof_278be873",
"name": "work"
}
```
You can also rename the profile:
```bash
curl -X PATCH http://localhost:9867/profiles/prof_278be873 \
-H "Content-Type: application/json" \
-d '{"name":"work-renamed"}'
```
Important:
- `PATCH /profiles/{id}` requires the profile ID
- using the profile name in that path returns an error
- a rename changes the generated profile ID because IDs are derived from the name
## Delete A Profile
```bash
curl -X DELETE http://localhost:9867/profiles/prof_278be873
# Response
{
"status": "deleted",
"id": "prof_278be873",
"name": "work"
}
```
`DELETE /profiles/{id}` also requires the profile ID.
## Start Or Stop By Profile
Start the active instance for a profile:
```bash
curl -X POST http://localhost:9867/profiles/prof_278be873/start \
-H "Content-Type: application/json" \
-d '{"headless":true}'
# Response
{
"id": "inst_ea2e747f",
"profileId": "prof_278be873",
"profileName": "work",
"port": "9868",
"headless": true,
"status": "starting"
}
```
Stop the active instance for a profile:
```bash
curl -X POST http://localhost:9867/profiles/prof_278be873/stop
# Response
{
"status": "stopped",
"id": "prof_278be873",
"name": "work"
}
```
For these orchestrator routes, the path can be a profile ID or profile name.
## Check Whether A Profile Has A Running Instance
```bash
curl http://localhost:9867/profiles/prof_278be873/instance
# Response
{
"name": "work",
"running": true,
"status": "running",
"port": "9868",
"id": "inst_ea2e747f"
}
```
## Additional Profile Operations
### Reset A Profile
```bash
curl -X POST http://localhost:9867/profiles/prof_278be873/reset
```
This route requires the profile ID.
### Import A Profile
```bash
curl -X POST http://localhost:9867/profiles/import \
-H "Content-Type: application/json" \
-d '{"name":"imported-profile","sourcePath":"/path/to/existing/profile"}'
```
### Get Logs
```bash
curl http://localhost:9867/profiles/prof_278be873/logs
curl 'http://localhost:9867/profiles/work/logs?limit=50'
```
`logs` accepts either the profile ID or the profile name.
### Get Analytics
```bash
curl http://localhost:9867/profiles/prof_278be873/analytics
curl http://localhost:9867/profiles/work/analytics
```
`analytics` also accepts either the profile ID or the profile name.
## Related Pages
- [Instances](./instances.md)
- [Tabs](./tabs.md)
- [Config](./config.md)
|