Skip to main content

Response Formats

Understanding the different response formats and data structures returned by Easy Scrape API.

JSON Response Format (Default)​

The default response format returns structured JSON data with metadata about the execution.

Success Response Structure​

{
  "message": "Script executed successfully",
  "data": {
    // Your script's return value goes here
  },
  "executionTime": 1250,
  "logs": [
    "Debug message 1",
    "Debug message 2"
  ]
}

Response Fields​

FieldTypeDescription
messagestringHuman-readable success message
dataanyThe actual data returned by your script
executionTimenumberScript execution time in milliseconds
logsstring[]Array of console.log() messages from your script
note

The response format is identical whether you use the script or scriptBase64 parameter. The API automatically decodes Base64 scripts before execution, so the response structure remains the same.

Script Parameter Examples​

Using script Parameter​

Simple request using the standard script parameter:

{
  "url": "https://example.com",
  "script": "const title = await page.title(); return { title };"
}

Response:

{
  "message": "Script executed successfully",
  "data": {
    "title": "Example Domain"
  },
  "executionTime": 1250,
  "logs": []
}

Using scriptBase64 Parameter​

For complex scripts with quotes, template literals, or special characters:

{
  "url": "https://example.com",
  "scriptBase64": "Y29uc3QgdGl0bGUgPSBhd2FpdCBwYWdlLnRpdGxlKCk7IHJldHVybiB7IHRpdGxlIH07"
}

Response:

{
  "message": "Script executed successfully",
  "data": {
    "title": "Example Domain"
  },
  "executionTime": 1250,
  "logs": []
}
tip

The Base64 string Y29uc3QgdGl0bGUgPSBhd2FpdCBwYWdlLnRpdGxlKCk7IHJldHVybiB7IHRpdGxlIH07 decodes to the same JavaScript code as the script example above. Use our Online Code Parser Tool to convert your code to Base64 format.

HTML Response Format​

When outputFormat is set to "html", the API returns raw HTML content directly.

Request for HTML Output​

{
  "url": "https://example.com",
  "outputFormat": "html",
  "script": "return '<h1>Custom HTML Report</h1><p>Generated content</p>';"
}

HTML Response​

<h1>Custom HTML Report</h1>
<p>Generated content</p>

Error Response Format​

All errors follow a consistent JSON structure regardless of the requested output format.

Error Response Structure​

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "statusCode": 400
}

Error Response Fields​

FieldTypeDescription
errorstringDescriptive error message
codestringMachine-readable error identifier
statusCodenumberHTTP status code

Common Error Codes​

400 - Bad Request Errors​

Missing Required Field​

{
  "error": "Missing url",
  "code": "MISSING_REQUIRED_FIELD", 
  "statusCode": 400
}

Invalid URL Format​

{
  "error": "Invalid URL format",
  "code": "INVALID_URL_FORMAT",
  "statusCode": 400
}

Script Execution Failed​

{
  "error": "Script execution failed: ReferenceError: undefinedVariable is not defined",
  "code": "SCRAPING_FAILED",
  "statusCode": 400
}

Script Timeout​

{
  "error": "Script execution timeout after 30 seconds",
  "code": "EXECUTION_TIMEOUT", 
  "statusCode": 400
}

401 - Authentication Errors​

Missing API Key​

{
  "error": "API key is required",
  "code": "MISSING_API_KEY",
  "statusCode": 401
}

Invalid API Key​

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY", 
  "statusCode": 401
}

500 - Server Errors​

{
  "error": "Internal server error",
  "code": "INTERNAL_SERVER_ERROR",
  "statusCode": 500
}

Data Types and Validation​

Supported Return Types​

Your script can return any JSON-serializable data:

Primitive Types​

// String
return "Simple text result";

// Number  
return 42;

// Boolean
return true;

// Null
return null;

Objects​

return {
  title: "Page Title",
  count: 5,
  active: true,
  metadata: {
    scraped_at: new Date().toISOString()
  }
};

Arrays​

return [
  { name: "Item 1", value: 100 },
  { name: "Item 2", value: 200 }
];

Unsupported Return Types​

These will cause serialization errors:

// Functions
return function() { console.log("test"); }; // ❌

// DOM Elements  
return document.querySelector("div"); // ❌

// Puppeteer v24 Objects
return page; // ❌

// Circular References
const obj = {};
obj.self = obj;
return obj; // ❌

Response Size Limits​

Practical Limits​

  • Recommended: Keep responses under 1MB for best performance
  • Maximum: 10MB response size limit
  • Timeout: 30-second execution limit

Response Headers​

Success Responses​

HTTP/1.1 200 OK
Content-Type: application/json
X-Execution-Time: 1250
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

HTML Responses​

HTTP/1.1 200 OK  
Content-Type: text/html
X-Execution-Time: 1850
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

Error Responses​

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Error-Code: SCRAPING_FAILED

Character Encoding​

All responses use UTF-8 encoding and properly handle:

  • International characters
  • Emojis and symbols
  • Special HTML entities
  • Non-Latin scripts