Skip to main content
POST /tabs/:tabId/navigate
Navigates the tab to a new URL or search query using macros.

​
Path parameters

​
tabId
string
required
The unique identifier of the tab

​
Body parameters

​
userId
string
required
User identifier for session isolation
​
url
string
Direct URL to navigate to (e.g., https://example.com). Either url or macro is required.
​
macro
string
Search macro name (e.g., @google_search, @youtube_search). Either url or macro is required.
​
query
string
Search query to use with macro (required if macro is provided)
​
sessionKey
string
Session key for grouping tabs (legacy parameter: listItemId also accepted)

​
Response

​
ok
boolean
Always true on success
​
tabId
string
The tab identifier
​
url
string
The final URL after navigation (may differ from requested URL due to redirects)
​
refsAvailable
boolean
Whether element references were successfully built for the loaded page

​
Search macros

Macros expand to search URLs for popular websites:
MacroExpands to
@google_searchhttps://www.google.com/search?q={query}
@youtube_searchhttps://www.youtube.com/results?search_query={query}
@amazon_searchhttps://www.amazon.com/s?k={query}
@reddit_searchhttps://www.reddit.com/search.json?q={query}&limit=25
@wikipedia_searchhttps://en.wikipedia.org/wiki/Special:Search?search={query}
@twitter_searchhttps://twitter.com/search?q={query}
@yelp_searchhttps://www.yelp.com/search?find_desc={query}
@linkedin_searchhttps://www.linkedin.com/search/results/all/?keywords={query}
@spotify_searchhttps://open.spotify.com/search/{query}
@netflix_searchhttps://www.netflix.com/search?q={query}
@instagram_searchhttps://www.instagram.com/explore/tags/{query}
@tiktok_searchhttps://www.tiktok.com/search?q={query}
@twitch_searchhttps://www.twitch.tv/search?term={query}
@reddit_subreddithttps://www.reddit.com/r/{query}.json?limit=25

​
Auto-tab creation

If the specified tabId doesn’t exist, a new tab is automatically created (up to session limits). This allows simplified workflows without separate /tabs POST.
  • Waits for domcontentloaded event (default timeout: 30s)
  • Attempts to wait for network idle (5s timeout, continues if missed)
  • Waits for framework hydration (React/Next.js/Vue detection)
  • Auto-dismisses common consent/privacy dialogs
  • Builds element references after page load
  • Resets cached snapshots and refs

​
Go back

POST /tabs/:tabId/back
Navigates to the previous page in the tab’s history.

​
Path parameters

​
tabId
string
required
The unique identifier of the tab

​
Body parameters

​
userId
string
required
User identifier for session isolation

​
Response

​
ok
boolean
Always true on success
​
url
string
The URL after navigating back

​
Go forward

POST /tabs/:tabId/forward
Navigates to the next page in the tab’s history.

​
Path parameters

​
tabId
string
required
The unique identifier of the tab

​
Body parameters

​
userId
string
required
User identifier for session isolation

​
Response

​
ok
boolean
Always true on success
​
url
string
The URL after navigating forward

​
Refresh page

POST /tabs/:tabId/refresh
Reloads the current page.

​
Path parameters

​
tabId
string
required
The unique identifier of the tab

​
Body parameters

​
userId
string
required
User identifier for session isolation

​
Response

​
ok
boolean
Always true on success
​
url
string
The current URL (unchanged)

​
Error codes

  • 400 - Missing required parameter or invalid URL scheme (only http/https allowed)
  • 404 - Tab not found
  • 429 - Maximum tabs per session reached (when auto-creating tab)
  • 500 - Navigation failed (timeout, network error)

​
Examples

curl -X POST http://localhost:9377/tabs/abc123/navigate \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "url": "https://example.com"
  }'

{
  "ok": true,
  "tabId": "abc123",
  "url": "https://example.com/",
  "refsAvailable": true
}

​
Search using macro

curl -X POST http://localhost:9377/tabs/abc123/navigate \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "macro": "@google_search",
    "query": "headless browser automation"
  }'

{
  "ok": true,
  "tabId": "abc123",
  "url": "https://www.google.com/search?q=headless+browser+automation",
  "refsAvailable": true
}

​
Go back in history

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

{
  "ok": true,
  "url": "https://example.com"
}

​
Go forward in history

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

{
  "ok": true,
  "url": "https://example.com/page2"
}

​
Refresh page

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

{
  "ok": true,
  "url": "https://example.com"
}

​
Best practices

  1. Use macros for search: Simpler and more maintainable than manually constructing URLs
  2. Check refsAvailable: If false, the page may still be loading - wait and retry /snapshot
  3. Handle redirects: The returned url may differ from the requested URL
  4. Allow timeout buffer: Complex sites may take 10-20s to fully load
  5. Call /snapshot after navigation: Element refs are rebuilt but not returned in navigate response

Build docs developers (and LLMs) love

Get started for freeTalk to us