API Reference

The NextRows API enables you to extract structured data from any website using AI-powered natural language processing. This reference provides complete documentation for all endpoints, parameters, and response formats.

Quick Start

Get started with a simple extraction request:

cURL

curl -X POST https://api.nextrows.com/v1/extract \
  -H "Authorization: Bearer sk-nr-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "data": ["https://example.com"],
    "prompt": "Extract product names and prices"
  }'

Base URL

All API requests use the following base URL:

https://api.nextrows.com

Authentication

All requests require authentication using your API key in the Authorization header:

Authorization: Bearer sk-nr-your-api-key-here

Keep your API key secure! Never expose it in client-side code or public repositories.

Endpoints

Extract Data

Extract structured data from websites using natural language prompts.

Credit Usage

Check your current credit balance and usage statistics.

Core Parameters

Extract Endpoint Parameters

Parameter	Type	Required	Description
`type`	string	✅	Type of extraction: `"url"` or `"text"`
`data`	array	✅	URLs or text content to extract from (max 20 items)
`prompt`	string	❌	Natural language description of what to extract (max 2000 characters)
`schema`	object	❌	JSON Schema for data validation

Extraction Types

URL Extraction

Extract data directly from web pages:

{
  "type": "url",
  "data": [
    "https://example.com/page1",
    "https://example.com/page2"
  ],
  "prompt": "Extract product information"
}

Text Extraction

Extract data from provided text content:

{
  "type": "text",
  "data": [
    "Product: iPhone 14\nPrice: $999\nRating: 4.5/5",
    "Product: Samsung Galaxy\nPrice: $899\nRating: 4.3/5"
  ],
  "prompt": "Extract product name, price, and rating"
}

Response Format

Success Response

{
  "success": true,
  "data": [
    {
      "field1": "value1",
      "field2": "value2"
    }
  ]
}

Error Response

{
  "success": false,
  "error": "Detailed error message"
}

HTTP Status Codes

NextRows uses conventional HTTP status codes:

Status	Meaning	Description
200	Success	Request completed successfully
400	Bad Request	Invalid parameters or request format
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits
404	Not Found	Endpoint not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred
503	Service Unavailable	Service temporarily unavailable

Schema Validation

Use JSON Schema to ensure extracted data matches your expected structure:

Schema Example

{
  "type": "url",
  "data": ["https://jobs.example.com"],
  "prompt": "Extract job listings",
  "schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1
        },
        "company": {
          "type": "string"
        },
        "salary": {
          "type": "number",
          "minimum": 0
        },
        "location": {
          "type": "string"
        }
      },
      "required": ["title", "company"]
    }
  }
}

Schema Benefits

Type Safety: Ensure correct data types
Data Validation: Catch extraction errors early
Consistency: Standardize output format
Quality Control: Validate required fields

Advanced Features

Batch Processing

Process multiple URLs efficiently:

{
  "type": "url",
  "data": [
    "https://site1.com/products",
    "https://site2.com/products",
    "https://site3.com/products"
  ],
  "prompt": "Extract product catalog from each site"
}

Rate Limits

Limit Type	Value	Upgrade Options
Requests per minute	20	Fixed limit
URLs per request	20	Fixed limit

Error Handling

Common Errors

Invalid API Key

{
  "success": false,
  "error": "Unauthorized"
}

Credits Exhausted

{
  "success": false,
  "error": "Credits exhausted"
}

Extraction Failed

{
  "success": false,
  "error": "Failed to extract data"
}

Best Practices for Error Handling

Python Example

import requests
import time

def extract_with_retry(url, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://api.nextrows.com/v1/extract",
                headers={"Authorization": "Bearer sk-nr-your-api-key"},
                json={
                    "type": "url",
                    "data": [url],
                    "prompt": prompt
                }
            )
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # Rate limited - wait and retry
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            else:
                # Other error - don't retry
                response.raise_for_status()
                
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(1)
    
    raise Exception("Max retries exceeded")

Credit System

Credit Consumption

Different extraction types consume different amounts of credits:

Extraction Type	Base Cost	Factors
Simple text	1 credit	Per request
Basic URL	2-5 credits	Page complexity
Complex extraction	5-10 credits	AI processing required

Monitoring Usage

Check your credit usage:

Check Credits

curl -X GET https://api.nextrows.com/v1/credits \
  -H "Authorization: Bearer sk-nr-your-api-key"

Response:

{
  "success": true,
  "data": {
    "credits": 755
  }
}

Examples by Use Case

E-commerce

Extract product catalogs, prices, and reviews

Job Boards

Scrape job listings and career information

Real Estate

Extract property listings and market data

News & Content

Aggregate articles and content feeds

Additional Resources

Quick Start Guide: Get up and running in minutes
Examples: Real-world use cases and code samples
Troubleshooting: Common issues and solutions
Features: Advanced capabilities and options