Files API - PricingSaaS Intelligence API

Overview

The Files API provides access to historical scrape files for pricing pages. Each scrape includes multiple file formats:

Screenshot - Visual screenshot of the pricing page (Cloudinary)
Markdown - Text content extracted in markdown format (S3)
HTML - Full HTML source of the page (S3)
OCR - OCR data in JSON format (Supabase Storage)

All endpoints require authentication and cost 1 credit per request.

Get Files by Flexible Period (Recommended)

Retrieve scrape files using any supported period format. This unified endpoint automatically detects the format and returns the appropriate results.

slug

string

required

Company slug (e.g., “stripe”, “anthropic.com”)

period

string

required

Period in any supported format:

Version: YYYYMMDD (e.g., 20251010 for October 10, 2025)
Quarter: YYYYQ# (e.g., 2025Q4 for Q4 2025)
Week: YYYYW## (e.g., 2025W42 for week 42 of 2025)
Month: YYYYM## or YYYY## (e.g., 2025M12 or 202512 for December 2025)

The endpoint automatically detects which format you’re using.

Request

cURL

curl -X GET "https://api.pricingsaas.com/functions/v1/api/files/stripe/period/2025Q4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

files

array

Array of scrape file objects

Show ScrapeFile Object

slug

string

Company slug identifier

version

string

Scrape version in YYYYMMDD format

page_url

string

URL of the original pricing page

screenshot_url

string | null

Cloudinary URL to screenshot image

markdown_url

string | null

S3 URL to markdown version

html_url

string | null

S3 URL to HTML version

ocr_url

string | null

Supabase storage URL to OCR JSON

valid

boolean | null

Whether the scrape is valid

score

integer | null

Quality score (0-10)

count

integer

Number of files returned

period

object

Period range information

Show Period Object

start

string

Period start date in YYYYMMDD format

end

string

Period end date in YYYYMMDD format

format

string

Detected format type: version, quarter, week, or month

version

string | null

The specific version returned. For periods (quarter/week/month), this is the earliest version in the range.

{
  "files": [
    {
      "slug": "stripe",
      "version": "20251001",
      "page_url": "https://stripe.com/pricing",
      "screenshot_url": "https://res.cloudinary.com/dd6dkaan9/image/upload/v1753010719/pricing_pages/pricing_stripe_20251001.jpg",
      "markdown_url": "https://pricingsaas-scrapes.s3.amazonaws.com/stripe/20251001/pricingpage.md",
      "html_url": "https://pricingsaas-scrapes.s3.amazonaws.com/stripe/20251001/pricingpage.html",
      "ocr_url": "https://qulnbyjrczvoxemtrili.supabase.co/storage/v1/object/public/pricingsaas/stripe/20251001/ocr.json",
      "valid": true,
      "score": 9
    }
  ],
  "count": 1,
  "period": {
    "start": "20251001",
    "end": "20251231"
  },
  "format": "quarter",
  "version": "20251001"
}

Behavior for Period Formats: When using quarter, week, or month formats, the endpoint returns files from the earliest version within that period, not all versions.

Format-Specific Endpoints

While the unified period endpoint is recommended, you can also use format-specific endpoints:

Get Files by Version

GET /files/{slug}/version/{version}

Retrieve scrape files for a specific date. Example:

curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/version/20251010" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Files by Quarter

GET /files/{slug}/quarter/{quarter}

Retrieve scrape files for a specific quarter. Quarter Mappings:

Q1 = January - March
Q2 = April - June
Q3 = July - September
Q4 = October - December

Example:

curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/quarter/2025Q4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Files by Month

GET /files/{slug}/month/{month}

Retrieve scrape files for a specific month. Supports both YYYYM## and YYYY## formats. Example:

curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/month/2025M12" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Files by ISO Week

GET /files/{slug}/week/{week}

Retrieve scrape files for a specific ISO 8601 week (Monday-Sunday). Example:

curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/week/2025W42" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code Examples

const API_KEY = process.env.PRICINGSAAS_API_KEY;

async function getFilesByPeriod(slug, period) {
  const url = `https://api.pricingsaas.com/functions/v1/api/files/${slug}/period/${period}`;

  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error);
    throw new Error(error.error);
  }

  return response.json();
}

// Works with any format!
const filesQ4 = await getFilesByPeriod('stripe', '2025Q4');
const filesDate = await getFilesByPeriod('stripe', '20251010');
const filesWeek = await getFilesByPeriod('stripe', '2025W42');

console.log(`Format: ${filesQ4.format}`);
console.log(`Period: ${filesQ4.period.start} to ${filesQ4.period.end}`);
console.log(`Files found: ${filesQ4.count}`);

Use Cases

Track Pricing Changes Over Time

Monitor how a competitor’s pricing evolves quarter over quarter:

# Get Q3 2025 files
curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/period/2025Q3" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get Q4 2025 files
curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/period/2025Q4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Download Pricing Pages for Analysis

Retrieve markdown files for text analysis:

const files = await getFilesByPeriod('stripe', '2025Q4');

for (const file of files.files) {
  if (file.markdown_url && file.valid && file.score >= 8) {
    const markdown = await fetch(file.markdown_url).then(r => r.text());
    // Analyze pricing data
  }
}

Compare Multiple Companies

Fetch files from multiple companies for the same period:

# Get all major SaaS pricing for Q4 2025
curl "https://api.pricingsaas.com/functions/v1/api/files/stripe/period/2025Q4" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.pricingsaas.com/functions/v1/api/files/openai/period/2025Q4" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.pricingsaas.com/functions/v1/api/files/anthropic/period/2025Q4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Cache responses aggressively

Files don’t change after creation, so you can cache responses indefinitely for the same version/period.

Use the unified period endpoint

The /period/{period} endpoint is more flexible and reduces the need to remember multiple endpoint formats.

Filter by quality scores

Check the valid and score fields to filter for high-quality scrapes (score >= 8 recommended).

Handle empty results

Not all companies have scrapes for all periods. Always check if files array is empty before processing.

Respect rate limits

Each request costs 1 credit. Monitor your credit usage to avoid hitting rate limits.

Error Handling

INVALID_PERIOD_FORMAT

400

The period format was not recognized. Check the error details for valid format examples.

INVALID_QUARTER

400

Quarter must be between 1 and 4 (e.g., Q1, Q2, Q3, Q4).

INVALID_WEEK

400

Week must be between 1 and 53 for ISO week format.

INVALID_MONTH

400

Month must be between 1 and 12.

INVALID_VERSION

400

Version must be a valid date in YYYYMMDD format.

AUTH_INVALID

401

Invalid or missing API key. Include your API key in the Authorization header.

INSUFFICIENT_CREDITS

429

You don’t have enough credits to make this request. Credits reset monthly.

DB_ERROR

500

Database query failed. Contact support if this persists.

Rate Limiting

This endpoint costs 1 credit per request (all format variations). See Rate Limits for more information.

Companies API

Get company data to find available slugs

Pricing Pages API

Get pricing page metadata

Rate Limits

Learn about credit system and limits

Error Handling

Handle API errors gracefully

API Reference

​Overview

​Get Files by Flexible Period (Recommended)

​Request

​Response

​Format-Specific Endpoints

​Get Files by Version

​Get Files by Quarter

​Get Files by Month

​Get Files by ISO Week

​Code Examples

​Use Cases

​Track Pricing Changes Over Time

​Download Pricing Pages for Analysis

​Compare Multiple Companies

​Best Practices

​Error Handling

​Rate Limiting

​Related Resources

Companies API

Pricing Pages API

Rate Limits

Error Handling

Overview

Get Files by Flexible Period (Recommended)

Request

Response

Format-Specific Endpoints

Get Files by Version

Get Files by Quarter

Get Files by Month

Get Files by ISO Week

Code Examples

Use Cases

Track Pricing Changes Over Time

Download Pricing Pages for Analysis

Compare Multiple Companies

Best Practices

Error Handling

Rate Limiting

Related Resources