⚡ Pro Plan Feature

API Reference

Programmatic access to your tracked products, price history, and exports. Build automations, feed dashboards, or integrate DataSpout into your data pipeline.

🔍

Track Products

Add URLs and get automated price monitoring across major retailers

📈

Price History

Full historical price data with timestamps for any tracked product

📦

Bulk Export

CSV and JSON exports of your entire product dataset

⚡

Real-time

Fresh data every 6 hours with on-demand scrape triggers

Authentication

All API requests require an API key passed in the Authorization header. You can find your API key in the Dashboard under Settings.

HTTP Header

Authorization: Bearer ds_live_your_api_key_here

🛈

API keys start with ds_live_ for production and ds_test_ for sandbox. Keep your keys secret — never commit them to source control.

bash

curl https://dataspout.polsia.app/api/products \
  -H "Authorization: Bearer ds_live_your_api_key_here"

javascript

const response = await fetch('https://dataspout.polsia.app/api/products', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

const data = await response.json();
console.log(data);

Base URL

All endpoints are relative to the base URL:

Base URL https://dataspout.polsia.app/api

All responses return JSON. Requests that include a body should set Content-Type: application/json.

Rate Limits

Rate limits are enforced per API key and vary by plan. Exceeding your limit returns 429 Too Many Requests.

Plan	Price	Requests / Day	Products
Free	$0/mo	100	5
Starter	$29/mo	1,000	50
Pro	$79/mo	10,000	Unlimited

🚀

Need higher limits? Pro plan includes 10,000 requests/day and unlimited products. Compare plans →

Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1717459200

Endpoints

GET /api/products List tracked products ▶

Returns all products being tracked for your account. Supports filtering and sorting.

Query Parameters

Parameter	Type	Required	Description
status	string	optional	Filter by status: `active`, `paused`, `error`
sort	string	optional	Sort field: `name`, `price`, `created_at`
search	string	optional	Search product names and URLs

bash

curl "https://dataspout.polsia.app/api/products?status=active&sort=price" \
  -H "Authorization: Bearer ds_live_your_api_key_here"

javascript

const res = await fetch('https://dataspout.polsia.app/api/products?status=active', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const products = await res.json();

Response — 200 OK

json

{
  "products": [
    {
      "id": 142,
      "name": "Sony WH-1000XM5 Headphones",
      "url": "https://www.amazon.com/dp/B09XS7JWHH",
      "current_price": 328.00,
      "currency": "USD",
      "lowest_price": 278.00,
      "highest_price": 399.99,
      "status": "active",
      "last_scraped_at": "2026-05-06T08:00:00Z",
      "created_at": "2026-04-28T14:30:00Z"
    }
  ],
  "total": 1
}

GET /api/products/:id Get a single product ▶

Retrieve details for a single tracked product by its ID.

Path Parameters

Parameter	Type	Required	Description
id	integer	required	The product ID

bash

curl https://dataspout.polsia.app/api/products/142 \
  -H "Authorization: Bearer ds_live_your_api_key_here"

javascript

const res = await fetch('https://dataspout.polsia.app/api/products/142', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const product = await res.json();

Response — 200 OK

json

{
  "id": 142,
  "name": "Sony WH-1000XM5 Headphones",
  "url": "https://www.amazon.com/dp/B09XS7JWHH",
  "current_price": 328.00,
  "currency": "USD",
  "lowest_price": 278.00,
  "highest_price": 399.99,
  "price_change": -21.99,
  "price_change_pct": -6.28,
  "status": "active",
  "category": "Electronics",
  "last_scraped_at": "2026-05-06T08:00:00Z",
  "created_at": "2026-04-28T14:30:00Z"
}

POST /api/products Add a product to track ▶

Start tracking a new product by URL. DataSpout automatically extracts the product name, current price, and begins monitoring for changes every 6 hours.

Request Body

Parameter	Type	Required	Description
url	string	required	Product URL to track (Amazon, Best Buy, Target, Walmart, eBay, Newegg)
category	string	optional	Category label for organizing products

bash

curl -X POST https://dataspout.polsia.app/api/products \
  -H "Authorization: Bearer ds_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B09XS7JWHH",
    "category": "Electronics"
  }'

javascript

const res = await fetch('https://dataspout.polsia.app/api/products', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://www.amazon.com/dp/B09XS7JWHH',
    category: 'Electronics'
  })
});
const product = await res.json();

Response — 201 Created

json

{
  "id": 143,
  "name": "Sony WH-1000XM5 Headphones",
  "url": "https://www.amazon.com/dp/B09XS7JWHH",
  "current_price": 328.00,
  "currency": "USD",
  "status": "active",
  "category": "Electronics",
  "created_at": "2026-05-06T12:30:00Z",
  "message": "Product added. First price check in progress."
}

GET /api/products/:id/prices Get price history ▶

Returns the full price history for a tracked product. Prices are recorded every 6 hours and stored as immutable events — no data is ever overwritten.

Path Parameters

Parameter	Type	Required	Description
id	integer	required	The product ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	optional	Max records to return. Default: 100, Max: 1000

bash

curl "https://dataspout.polsia.app/api/products/142/prices?limit=50" \
  -H "Authorization: Bearer ds_live_your_api_key_here"

javascript

const res = await fetch('https://dataspout.polsia.app/api/products/142/prices?limit=50', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const history = await res.json();

// Plot prices over time
history.prices.forEach(p =>
  console.log(`${p.recorded_at}: $${p.price}`)
);

Response — 200 OK

json

{
  "product_id": 142,
  "prices": [
    {
      "price": 328.00,
      "currency": "USD",
      "recorded_at": "2026-05-06T08:00:00Z"
    },
    {
      "price": 349.99,
      "currency": "USD",
      "recorded_at": "2026-05-06T02:00:00Z"
    },
    {
      "price": 349.99,
      "currency": "USD",
      "recorded_at": "2026-05-05T20:00:00Z"
    }
  ],
  "total": 3
}

GET /api/export/:format Export all data ▶

Export your entire product dataset with the latest prices. Available in CSV and JSON formats. Perfect for feeding into spreadsheets, databases, or analytics pipelines.

Path Parameters

Parameter	Type	Required	Description
format	string	required	`csv` or `json`

bash

# Export as CSV
curl https://dataspout.polsia.app/api/export/csv \
  -H "Authorization: Bearer ds_live_your_api_key_here" \
  -o products.csv

# Export as JSON
curl https://dataspout.polsia.app/api/export/json \
  -H "Authorization: Bearer ds_live_your_api_key_here" \
  -o products.json

javascript

import { writeFileSync } from 'fs';

// Download CSV
const res = await fetch('https://dataspout.polsia.app/api/export/csv', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const csv = await res.text();
writeFileSync('products.csv', csv);

// Or get JSON for programmatic use
const jsonRes = await fetch('https://dataspout.polsia.app/api/export/json', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const data = await jsonRes.json();

📋

CSV exports include headers: id, name, url, current_price, currency, lowest_price, highest_price, status, last_scraped_at, created_at

Error Codes

The API uses standard HTTP status codes. Errors return a JSON body with a message field.

200 Success. Response body contains the requested data.

201 Created. New resource successfully created.

400 Bad Request. Check your request parameters.

401 Unauthorized. API key is missing or invalid.

403 Forbidden. Your plan doesn't include API access.

404 Not Found. The requested resource doesn't exist.

429 Rate limit exceeded. Back off and retry after the reset time.

500 Server error. Try again or contact support.

Error Response

{
  "error": "rate_limit_exceeded",
  "message": "You've exceeded 100 requests/day on the Free plan.",
  "upgrade_url": "https://dataspout.polsia.app/pricing"
}

Response Format

All responses are JSON with Content-Type: application/json (except CSV exports). Timestamps are ISO 8601 in UTC. Prices are numeric (not string), always in the product's detected currency.

Pagination

List endpoints return a total count alongside the array. Use the limit parameter to control response size.

Null Handling

Fields that haven't been populated yet (e.g. lowest_price before the second scrape) return null, never an empty string or zero.

Start building with DataSpout

Pro plan includes full API access, 10,000 requests/day, and unlimited products.

View Plans →