PerimeterX Solver API

Solve PerimeterX-protected pages with the Solverify PerimeterX Solver API. Create a browser-based task with the target URL, PerimeterX application ID, and proxy, then retrieve the resulting PerimeterX cookies from solution.cookies.

Use this task type when your authorized integration knows the target page and its PerimeterX pxAppId.

The PerimeterX integration follows the standard Solverify task workflow:

Identify the target URL and PerimeterX pxAppId.
Create a perimeterx task with a proxy.
Store the returned taskId.
Poll POST /getTaskResult until the task completes.
Read cookies and the solver user-agent from solution.

Request Parameters

Field	Type	Required	Description
`clientKey`	string	Yes	Your private Solverify API key.
`task.type`	string	Yes	Must be `perimeterx`.
`task.websiteURL`	string	Yes	Full URL of the PerimeterX-protected target page. Maximum 2,048 characters.
`task.websiteKey`	string	Yes	PerimeterX application ID, also known as `pxAppId`. Maximum 256 characters.
`task.useragent`	string	No	User-agent to use for the browser session. If omitted, the solver returns its browser user-agent.
`task.proxyType`	string	Yes	Proxy type. Only `http` is accepted.
`task.proxyAddress`	string	Yes	Proxy IP address or hostname. Maximum 256 characters.
`task.proxyPort`	string	Yes	Proxy port as a numeric string containing 1 to 5 digits.
`task.proxyLogin`	string	No	Username for an authenticated proxy.
`task.proxyPassword`	string	No	Password for an authenticated proxy.

Use the same proxy and solution.useragent when replaying returned PerimeterX cookies in a follow-up request.

Create PerimeterX Task Request

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "perimeterx",
    "websiteURL": "https://example.com",
    "websiteKey": "PXHYx10rg3",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
    "proxyType": "http",
    "proxyAddress": "1.1.1.1",
    "proxyPort": "8080",
    "proxyLogin": "username",
    "proxyPassword": "password"
  }
}

Omit proxyLogin and proxyPassword when the proxy does not require authentication.

PerimeterX Solver Code Examples

These examples create a PerimeterX task and print the returned task ID.

curl --request POST \
  --url https://solver.solverify.net/createTask \
  --header "Content-Type: application/json" \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "perimeterx",
      "websiteURL": "https://example.com",
      "websiteKey": "PXHYx10rg3",
      "proxyType": "http",
      "proxyAddress": "1.1.1.1",
      "proxyPort": "8080"
    }
  }'

Create Task Response

{
  "errorId": 0,
  "taskId": "UUID"
}

Completed PerimeterX Result

{
  "errorId": 0,
  "status": "completed",
  "solution": {
    "value": "",
    "cookies": {
      "_px3": "37624",
      "_pxvid": "254"
    },
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36"
  },
  "errorCode": null,
  "errorDescription": null
}

Solution Fields

Field	Description
`cookies`	Cookies captured from the solved PerimeterX browser session.
`useragent`	User-agent used by the solver. Replay cookies with this value.

Cookie names vary by target configuration. Common values include _px3, _pxvid, and _pxhd when issued by the target.

PerimeterX Timeout

PerimeterX tasks can run for up to approximately 180 seconds before timing out internally. Configure an overall polling deadline and stop when the API returns an error.

PerimeterX API Errors

Error code	Description
`ERROR_INVALID_REQUEST`	The top-level request is missing or contains invalid JSON.
`ERROR_INVALID_TASK`	The PerimeterX URL, application ID, or proxy settings are missing or invalid.
`ERROR_INSUFFICIENT_BALANCE`	The account balance is too low to create the task.
`ERROR_NO_CAPACITY`	PerimeterX solver capacity is temporarily unavailable.
`ERROR_TASK_FAILED`	The PerimeterX challenge could not be completed.
`ERROR_TIMEOUT`	Solving exceeded the allowed processing time.

For recovery guidance and every supported response, see Solverify API Error Codes.

Next Steps

After creating a PerimeterX task, poll the Get Task Result API every 2 to 3 seconds with the returned taskId. Stop polling after completion or failure.

Frequently Asked Questions

What is `websiteKey` for PerimeterX?

websiteKey is the PerimeterX application ID, commonly called pxAppId.

Does the PerimeterX solver require a proxy?

Yes. Provide proxyType, proxyAddress, and proxyPort. Add proxy credentials only when authentication is required.

Should I send `uuid` or `vid`?

No. These legacy fields are accepted by the backend but are not consumed by the current Node solver. Omit them from new task requests.

What cookies does the PerimeterX API return?

The solver returns cookies captured from the browser session in solution.cookies. Exact cookie names depend on the target configuration.

Why should I reuse the proxy and user-agent?

Reusing the proxy and solution.useragent preserves the browser session context associated with the returned cookies.