Skip to main content

​
Real-time URL Requests

Real-time requests provide immediate responses for single URL scraping with low latency and high reliability.

​
Basic Real-time Request

​
Endpoint

POST https://api.nimbleway.com/v1/scrape

​
Simple Request

curl -X POST "https://api.nimbleway.com/v1/scrape" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "html"
  }'

​
Response

{
  "status": "success",
  "url": "https://example.com",
  "html": "<!DOCTYPE html><html>...",
  "response_code": 200,
  "response_time": 1.23,
  "headers": {
    "content-type": "text/html; charset=utf-8",
    "server": "nginx/1.18.0"
  }
}

​
Request Parameters

​
Required Parameters

ParameterTypeDescription
urlstringTarget URL to scrape

​
Optional Parameters

ParameterTypeDefaultDescription
formatstringhtmlResponse format: html, json, text
renderbooleanfalseEnable JavaScript rendering
countrystringUSProxy country code
timeoutinteger30Request timeout in seconds
retriesinteger3Number of retry attempts
user_agentstringautoCustom user agent string

​
Advanced Options

​
JavaScript Rendering

Enable JavaScript rendering for dynamic content: 
{
  "url": "https://spa-example.com",
  "render": true,
  "wait_for": "networkidle0",
  "timeout": 60
}

​
Geographic Targeting

Specify proxy location for geo-targeted content: 
{
  "url": "https://geo-specific-site.com",
  "country": "GB",
  "city": "London"
}

​
Custom Headers

Add custom headers to your request: 
{
  "url": "https://api-endpoint.com",
  "headers": {
    "Accept": "application/json",
    "X-Custom-Header": "value"
  }
}

​
Response Formats

​
HTML Format (Default)

{
  "status": "success",
  "url": "https://example.com",
  "html": "<!DOCTYPE html>...",
  "response_code": 200
}

​
JSON Format

{
  "status": "success", 
  "url": "https://api.example.com",
  "json": {
    "data": "parsed json response"
  },
  "response_code": 200
}

​
Text Format

{
  "status": "success",
  "url": "https://text-content.com", 
  "text": "Plain text content...",
  "response_code": 200
}

​
Error Handling

​
Common Error Responses

​
URL Not Accessible

{
  "status": "error",
  "error": "URL_NOT_ACCESSIBLE",
  "message": "The target URL returned a 404 error",
  "response_code": 404
}

​
Timeout Error

{
  "status": "error", 
  "error": "TIMEOUT",
  "message": "Request timed out after 30 seconds",
  "response_code": 408
}

​
Rate Limit Exceeded

{
  "status": "error",
  "error": "RATE_LIMIT_EXCEEDED", 
  "message": "Too many requests. Try again in 60 seconds",
  "response_code": 429,
  "retry_after": 60
}

​
SDK Examples

​
Node.js

import { NimbleClient } from '@nimbleway/sdk';

const client = new NimbleClient({
  apiKey: 'your-api-key'
});

try {
  const result = await client.scrape({
    url: 'https://example.com',
    render: true,
    country: 'US'
  });
  
  console.log(result.html);
} catch (error) {
  console.error('Scraping failed:', error.message);
}

​
Python

from nimble_sdk import NimbleClient

client = NimbleClient(api_key='your-api-key')

try:
    result = client.scrape({
        'url': 'https://example.com',
        'render': True,
        'country': 'US'
    })
    
    print(result['html'])
except Exception as error:
    print(f'Scraping failed: {error}')

​
Best Practices

​
Performance Optimization

  • Use appropriate timeouts - Balance speed vs reliability
  • Enable rendering only when needed - JavaScript rendering adds latency
  • Choose optimal proxy locations - Select closest available location
  • Implement retry logic - Handle temporary failures gracefully

​
Cost Optimization

  • Cache results when appropriate
  • Use batch requests for multiple URLs
  • Monitor your usage in the dashboard
  • Set reasonable timeouts to avoid long-running requests

​
Rate Limits

PlanRequests/SecondConcurrent Requests
Free11
Starter510
Professional2050
EnterpriseCustomCustom

​
Next Steps