Creating AI Agent Sessions

Start an AI browser agent session via the REST API. The agent will execute your task and return results.

Create a Session

POST https://api.scrayle.com/api/v1/ai/agent

Headers:
  Content-Type: application/json
  x-api-key: YOUR_API_KEY

Body:
{
  "task": "Go to amazon.com and find the top 5 wireless headphones under $50",
  "startUrl": "https://www.amazon.com",
  "model": "gemini-3-flash",
  "maxIterations": 25,
  "captchaSolver": false,
  "proxyCountry": "US"
}

Request Parameters

Parameter	Type	Required	Description
`task`	string	Yes	Natural language description of what to do
`startUrl`	string	No	Starting URL (agent navigates here first)
`model`	string	No	Model ID (default: gemini-3-flash)
`maxIterations`	number	No	Maximum steps (default: 25)
`captchaSolver`	boolean	No	Enable automatic CAPTCHA solving
`proxyCountry`	string	No	2-letter country code for proxy

Response

{
  "jobId": "job_abc123",
  "status": "queued"
}

Checking Status

GET https://api.scrayle.com/api/v1/ai/agent/{jobId}/status

Response:
{
  "jobId": "job_abc123",
  "status": "running",
  "progress": {
    "currentIteration": 12,
    "maxIterations": 25,
    "currentUrl": "https://www.amazon.com/s?k=wireless+headphones",
    "lastAction": "Clicking on the first product result"
  }
}

Getting Results

GET https://api.scrayle.com/api/v1/ai/agent/{jobId}/result

Response:
{
  "jobId": "job_abc123",
  "status": "completed",
  "result": {
    "extractedData": [...],
    "visitedUrls": [...],
    "iterationCount": 18,
    "finalScreenshot": "base64..."
  }
}

Streaming Progress

Connect to the real-time stream to get live updates as the agent works:

GET https://api.scrayle.com/api/v1/ai/agent/{jobId}/stream

// Server-Sent Events stream
// Each event contains the current step, screenshot, and action taken

Tips for Better Results

Be specific - "Find the price of iPhone 16 Pro on apple.com" works better than "Find iPhone prices"
Set a start URL - Providing a starting page helps the agent focus
Keep iterations reasonable - Most tasks complete in 10-20 iterations
Use budget models first - Try Gemini 3 Flash before upgrading to premium models
Enable CAPTCHA solver only when needed - it adds 3 credits to the cost

⚠️Search Engine Navigation

The agent automatically navigates to search engine homepages and uses the search box rather than URL query parameters. This avoids triggering bot detection on Google, Bing, and other search engines.