List Posts

GET/api/v1/content/posts

Overview

Returns a paginated list of published blog posts for the resolved client site. Supports filtering by tag and category.

Authentication

info

No authentication required - Client is resolved from the X-Content-Domain header, which the Cloudflare Worker sets automatically based on the request domain.

Headers

Header	Type	Required	Description
X-Content-Domain	string	Yes	The domain used to resolve the client tenant. Automatically set by the CF Worker; set manually for external frontend integrations (WeWeb, Webflow, custom).

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number for pagination
page_size	integer	20	Number of posts per page
tag	string	-	Filter posts by tag name
category	string	-	Filter posts by category name or UUID

Response

postsarray

Array of published post objects

posts[].idstring (UUID)

Unique post identifier

posts[].slugstring

URL-friendly slug

posts[].titlestring

Post title

posts[].excerptstring

Short excerpt / summary

posts[].cover_image_urlstring | null

URL of the cover image

posts[].statusstring

Always published for this endpoint

posts[].published_atstring

ISO 8601 publication timestamp

posts[].author_namestring

Author display name (flat field)

posts[].author_idstring (UUID)

Author identifier

posts[].authorobject

Nested author object with id, full_name, slug, avatar_url

posts[].reading_timeinteger

Estimated reading time in minutes

posts[].view_countinteger

Total view count

posts[].is_featuredboolean

Whether the post is featured

posts[].tagsstring[]

Array of tag names

totalinteger

Total number of matching posts

pageinteger

Current page number

page_sizeinteger

Number of posts per page

Example Request

cURL

curl -s "https://spideriq.ai/api/v1/content/posts?page=1&page_size=10&tag=seo" \
  -H "X-Content-Domain: your-domain.com"

Python

import requests

resp = requests.get(
    "https://spideriq.ai/api/v1/content/posts",
    params={"page": 1, "page_size": 10, "tag": "seo"},
    headers={"X-Content-Domain": "your-domain.com"}
)
data = resp.json()

for post in data["posts"]:
    print(f"{post['title']} — {post['published_at']}")
print(f"Total: {data['total']}")

JavaScript

const resp = await fetch(
  "https://spideriq.ai/api/v1/content/posts?page=1&page_size=10&tag=seo",
  { headers: { "X-Content-Domain": "your-domain.com" } }
);
const data = await resp.json();

data.posts.forEach(post => {
  console.log(`${post.title} — ${post.published_at}`);
});

Example Response

{
  "posts": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "slug": "how-to-scrape-google-maps",
      "title": "How to Scrape Google Maps at Scale",
      "excerpt": "A step-by-step guide to extracting business data from Google Maps using SpiderIQ.",
      "cover_image_url": "https://cdn.spideriq.ai/blog/maps-guide-cover.webp",
      "status": "published",
      "published_at": "2026-03-15T09:00:00Z",
      "author_name": "Martin Shein",
      "author_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "author": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "full_name": "Martin Shein",
        "slug": "martin-shein",
        "avatar_url": "https://cdn.spideriq.ai/authors/martin.webp"
      },
      "reading_time": 8,
      "view_count": 1243,
      "is_featured": true,
      "tags": ["google-maps", "scraping", "seo"]
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10
}

Status Codes

Status Code	Meaning	Description
200	OK	Posts returned successfully
422	Unprocessable Entity	Invalid query parameters

Related Endpoints

📃

Get Post

Get a single post by slug

⭐

Featured Posts

List featured posts

🔎

Search Posts

Full-text search across posts

tags

List Tags

List all tags with post counts