SPHYNX
esc
  • Loading
Open console

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}/elements

Every 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

    true when count is 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 name attribute. Left out when empty.

    • typestring

      The type attribute. Left out when empty.

    • hrefstring

      The link target. Left out when empty.

    • placeholderstring

      The placeholder attribute. 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 '{}'
200
{
  "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
    }
  ]
}
Body · every row of one table, by XPath
{
  "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 body · click the button found above
{
  "actions": [
    { "type": "click", "selector": "#login > button" }
  ]
}

Errors

The shape is the same as everywhere else: see Errors.

HTTPCodeWhen
400invalid_requestBad selector or XPath, more than one locator, unknown field, bad value
401unauthorizedMissing or invalid API key
404session_not_foundNo such session for this key
404tab_not_foundNo such tab
409no_page_loadedThe tab is blank
409session_in_useAnother drive call has been running on this session for more than 3 s
410session_closedThe session has ended
500internalOur fault. Send us the request_id