API reference
Actions
Run a list of steps in order, in one request.
A whole form flow is one round trip; a single click is a list of one. Steps run in the order given and stop at the first failure.
Run actions
POST/v1/sessions/{id}/actionsReturns 200 whether or not a step failed. Check ok in the response.
Path
- idstringrequired
The session to drive.
Body
- actionslist of steps, ≤50required
The steps to run. Each step has a
typeand the fields for that type, listed under Step types. - tab_idstringdefaultthe active tab
The tab every step runs in.
Response
- okbool
truewhen every step succeeded. - completedint
The number of steps that succeeded.
- resultslist
One entry per step that ran, in order.
- typestring
The step's
type. - okbool
Whether this step succeeded.
- duration_msint
How long the step took.
- errorobject
Only on a failed step:
codeandmessage.
- urlstring
The address of the page after the steps ran.
- titlestring
The title of that page.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/actions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"actions": [
{"type": "navigate", "url": "https://example.com/login"},
{"type": "fill", "selector": "#email",
"value": "me@example.com"},
{"type": "fill", "xpath": "//input[@name=\"password\"]",
"value": "hunter2"},
{"type": "click", "text": "Sign in"},
{"type": "wait", "selector": ".dashboard",
"timeout_ms": 10000}
]
}'const res = await fetch(`${process.env.SPHYNX_URL}/v1/sessions/${sessionId}/actions`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
actions: [
{ type: "navigate", url: "https://example.com/login" },
{ type: "fill", selector: "#email", value: "me@example.com" },
{ type: "fill", xpath: '//input[@name="password"]', value: "hunter2" },
{ type: "click", text: "Sign in" },
{ type: "wait", selector: ".dashboard", timeout_ms: 10000 },
],
}),
});
const result = await res.json();import os
import requests
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/sessions/{session_id}/actions",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={
"actions": [
{"type": "navigate", "url": "https://example.com/login"},
{"type": "fill", "selector": "#email", "value": "me@example.com"},
{"type": "fill", "xpath": '//input[@name="password"]', "value": "hunter2"},
{"type": "click", "text": "Sign in"},
{"type": "wait", "selector": ".dashboard", "timeout_ms": 10000},
]
},
timeout=60,
)
result = res.json(){
"ok": true,
"completed": 5,
"results": [
{ "type": "navigate", "ok": true, "duration_ms": 812 },
{ "type": "fill", "ok": true, "duration_ms": 96 },
{ "type": "fill", "ok": true, "duration_ms": 88 },
{ "type": "click", "ok": true, "duration_ms": 2140 },
{ "type": "wait", "ok": true, "duration_ms": 640 }
],
"url": "https://example.com/dashboard",
"title": "Dashboard"
}Step types
Where a step targets an element it takes a locator: exactly one of selector (CSS), xpath or text (visible text, case-insensitive substring). The first match is used. See Concepts.
Steps
- navigate
Loads a page. Same as Navigate.
- urlstring, http or httpsrequired
- wait_untilload or domcontentloadeddefaultload
- timeout_msint, ≤60000default30000
- click
Moves the pointer to the element and clicks.
- selector, xpath or textlocatorrequired
- fill
Focuses the field, clears it and sets the value.
- selector, xpath or textlocatorrequired
- valuestringrequired
- type
Types key by key with human timing. With a locator it clicks the element first; without one it types into whatever has focus.
- valuestringrequired
- selector, xpath or textlocator
- press
Presses one key.
- keystringrequired
Enter,Tab,Escape,ArrowDown,Backspace, or a single character.
- scroll
Scrolls by pixels, or scrolls an element into view.
- delta_yintdefault800
Pixels to scroll. Negative is up.
- selector, xpath or textlocator
Scroll this element into view instead.
- hover
Moves the pointer over the element.
- selector, xpath or textlocatorrequired
- wait
Waits for an element to be visible, or sleeps.
- selector, xpath or textlocator
Wait until this element is visible.
- timeout_msintdefault10000
How long to wait for the element.
- msint, ≤10000
With no locator: sleep this long.
{
"actions": [
{ "type": "navigate", "url": "https://example.com/login" },
{ "type": "click", "text": "Sign in" },
{ "type": "fill", "selector": "#email",
"value": "me@example.com" },
{ "type": "type", "value": "hello" },
{ "type": "press", "key": "Enter" },
{ "type": "scroll", "delta_y": 800 },
{ "type": "hover", "xpath": "//nav//a[1]" },
{ "type": "wait", "selector": ".dashboard",
"timeout_ms": 10000 }
]
}How long steps take
Steps act the way a person would, so some take seconds. Set your client's timeout for the whole list.
| Step | Time |
|---|---|
click, hover | About 1.5 to 4 s each. The pointer moves to the element along a human-like path |
type | About 0.1 s per character |
scroll by delta_y | The wheel turns at about 1000 px per second: the default 800 px takes about 0.8 s. A delta_y beyond roughly 25,000 px does not finish inside the 30 s a step gets |
fill on an element in view, press | Milliseconds |
click, hover, type, fill and scroll with a locator first wheel an element that is outside the viewport into view at the same rate, for at most 8000 px (about 8 s). Further away than that the page jumps to it.
When a step fails
The response is still 200, with ok: false. The failed step carries the error. Later steps do not run and are not listed.
A malformed request is rejected with 400 invalid_request before anything runs: an unknown type, a missing field, two locators on one step, or more than 50 steps. details.index names the bad step.
Only the shape of the request is checked up front. A selector or XPath the page cannot parse fails its own step with invalid_request, after the steps before it have run.
{
"ok": false,
"completed": 1,
"results": [
{ "type": "navigate", "ok": true, "duration_ms": 790 },
{
"type": "click", "ok": false, "duration_ms": 31,
"error": {
"code": "element_not_found",
"message": "no element matched"
}
}
],
"url": "https://example.com/login",
"title": "Log in"
}Errors
Step errors are reported inside results, on the step that failed.
| Code | When |
|---|---|
element_not_found | No element matched the locator |
wait_timeout | A wait step timed out |
navigation_timeout | The page did not reach wait_until in timeout_ms |
navigation_failed | DNS failure, connection refused, TLS error |
unsafe_url | Not http/https, or a private, loopback or link-local address |
no_page_loaded | The tab is blank |
invalid_request | A selector or XPath the page cannot parse |
internal | Our fault |
Request errors fail the whole call. The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, unknown type, missing field, two locators on one step, more than 50 steps |
| 401 | unauthorized | Missing or invalid API key |
| 404 | session_not_found | No such session for this key |
| 404 | tab_not_found | No such tab |
| 409 | session_in_use | Another drive call has been running on this session for more than 3 s |
| 410 | session_closed | The session has ended |
| 500 | internal | Our fault. Send us the request_id |