Items API

The Items API allows you to fetch collected data from your aggregators.

Endpoint

GET /api/v1/aggregators/{aggregator_id}/items

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fetchosaurus.com/api/v1/aggregators/{aggregator_id}/items"

Query Parameters

Parameter	Type	Description
limit	integer	Max items to return. Default: 100, max: 1000
cursor	string	Pagination cursor from previous response
since	ISO 8601	Return items created after this timestamp
source_id	string	Filter by specific source
schema_version	integer	Filter by exact schema version
schema_version_gt	integer	Schema version greater than
schema_version_ge	integer	Schema version greater than or equal
schema_version_lt	integer	Schema version less than
schema_version_le	integer	Schema version less than or equal
dedupe	boolean	Deduplicate results by identity hash

Response

{
  "items": [
    {
      "id": "clx1abc123",
      "source_id": "clx2def456",
      "schema_version": 2,
      "created_at": "2026-01-20T10:30:00Z",
      "data": {
        "title": "Senior DevOps Engineer",
        "company": "Acme Corp",
        "location": "Remote",
        "url": "https://acme.com/jobs/123",
        "tags": ["devops", "kubernetes"]
      }
    }
  ],
  "next_cursor": "48291",
  "has_more": true
}

Field	Description
items	Array of item objects
next_cursor	Cursor for fetching the next page
has_more	Whether more items exist

Pagination

The API uses cursor-based pagination:

1. Make initial request without cursor
2. If has_more is true, use next_cursor in the next request
3. Repeat until has_more is false

# First request
curl "https://api.fetchosaurus.com/api/v1/aggregators/{id}/items?limit=100"

# Next page
curl "https://api.fetchosaurus.com/api/v1/aggregators/{id}/items?limit=100&cursor=48291"

Tip

Cursor-based pagination is stable under concurrent inserts. New items won’t cause you to skip or duplicate items during pagination.

Examples

Get items from the last 24 hours

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fetchosaurus.com/api/v1/aggregators/{id}/items?since=2026-01-22T00:00:00Z"

Get items from a specific source

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fetchosaurus.com/api/v1/aggregators/{id}/items?source_id=clx2def456"

Get deduplicated items

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fetchosaurus.com/api/v1/aggregators/{id}/items?dedupe=true"

Filter by schema version

# Only items using schema v2 or later
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fetchosaurus.com/api/v1/aggregators/{id}/items?schema_version_ge=2"

Rate Limiting

API requests are rate-limited to 100 requests per minute. If you exceed this limit, you’ll receive a 429 Too Many Requests response.

Errors

Status	Description
400	Invalid request parameters
401	Missing or invalid API key
404	Aggregator not found
429	Rate limit exceeded
500	Internal server error