API reference
Elements
List the elements on the current page, each with a selector and an XPath you can pass back.
With no locator the call returns what a person could interact with: links, buttons, inputs, selects, textareas and elements with a click handler or button role. With a locator it returns every element that matches.
List elements
POST/v1/sessions/{id}/elementsEvery field is optional: an empty object lists the interactive elements of the active tab.
Path
- idstringrequired
The session to drive.
Body
- selectorstring
A CSS selector, for example
form button[type=submit]. - xpathstring
An XPath, for example
//table[@id='prices']//tr. - textstring
Visible text, matched as a case-insensitive substring, for example
Sign in. - visible_onlybooldefaulttrue
Leave out elements that are not visible.
- limitint, 1–300default60
The most elements to return.
- tab_idstringdefaultthe active tab
The tab to read.
Send at most one of selector, xpath and text. More than one is invalid_request.
Response
- countint
The number of matches before
limit. - truncatedbool
truewhencountis larger than the number of elements returned. - elementslist
The elements that matched, up to
limit.- selectorstring
A unique CSS selector for the element. Usable as a locator.
- xpathstring
The absolute XPath of the element. Usable as a locator.
- tagstring
The tag name, for example
input. - textstring
The element's text, trimmed to 200 characters. Left out when empty.
- rolestring
The element's role. Left out when empty.
- namestring
The
nameattribute. Left out when empty. - typestring
The
typeattribute. Left out when empty. - hrefstring
The link target. Left out when empty.
- placeholderstring
The
placeholderattribute. Left out when empty. - visiblebool
Whether the element is visible.
curl -s -X POST \
"$SPHYNX_URL/v1/sessions/$SESSION/elements" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch(`${process.env.SPHYNX_URL}/v1/sessions/${sessionId}/elements`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
const { elements } = await res.json();import os
import requests
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/sessions/{session_id}/elements",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={},
timeout=60,
)
elements = res.json()["elements"]{
"count": 2,
"truncated": false,
"elements": [
{
"selector": "#login > input:nth-of-type(1)",
"xpath": "/html/body/form[1]/input[1]",
"tag": "input",
"name": "email",
"type": "email",
"placeholder": "Email",
"visible": true
},
{
"selector": "#login > button",
"xpath": "/html/body/form[1]/button[1]",
"tag": "button",
"text": "Sign in",
"type": "submit",
"visible": true
}
]
}{
"xpath": "//table[@id='prices']//tr",
"limit": 300
}Pass an element back
Every element comes with a unique selector and an absolute xpath. Either can go straight into a later call as its locator: a step of Actions, a selection of Extract or the element of a Screenshot.
Locators are described in Concepts.
{
"actions": [
{ "type": "click", "selector": "#login > button" }
]
}Errors
The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Bad selector or XPath, more than one locator, unknown field, bad value |
| 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 | no_page_loaded | The tab is blank |
| 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 |