Pagination

Navigate through large result sets efficiently.

Overview

The API supports two pagination styles:

• Cursor-based (recommended) - Stable, efficient for large datasets
• Offset-based (legacy) - Simple, supports page jumping

---

Cursor-Based Pagination (Recommended)

Cursor-based pagination provides stable, efficient pagination for large datasets. Items won't shift between pages when new data is added.

Parameters

Parameter	Type	Description
first	integer (1-1000)	Number of items to return (forward pagination)
after	string	Cursor to paginate after (forward)
last	integer (1-1000)	Number of items to return (backward pagination)
before	string	Cursor to paginate before (backward)
include_total	boolean	Include total count (slower for large datasets)

Response Format

{
  "vulnerabilities": [...],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "eyJ2IjoxLC...",
    "end_cursor": "eyJ2IjoxLC...",
    "total_count": null
  }
}

Example: First Page

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?first=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "vulnerabilities": [
    {
      "id": "vuln_abc123",
      "title": "Reentrancy vulnerability",
      "severity": "high",
      "detected_at": "2026-01-10T12:00:00Z"
    },
    ...
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "eyJ2IjoxLCJ0cyI6IjIwMjYtMDEtMTBUMTI6MDA6MDBaIiwiaWQiOiJ2dWxuX2FiYzEyMyIsImQiOiJkZXNjIn0",
    "end_cursor": "eyJ2IjoxLCJ0cyI6IjIwMjYtMDEtMDlUMTU6MzA6MDBaIiwiaWQiOiJ2dWxuX3h5ejc4OSIsImQiOiJkZXNjIn0",
    "total_count": null
  }
}

Example: Next Page

Use end_cursor from the previous response:

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?first=20&after=eyJ2IjoxLCJ0cyI6IjIwMjYtMDEtMDlUMTU6MzA6MDBaIiwiaWQiOiJ2dWxuX3h5ejc4OSIsImQiOiJkZXNjIn0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: Previous Page

Use start_cursor with before and last parameters:

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?last=20&before=eyJ2IjoxLCJ0cyI6IjIwMjYtMDEtMTBUMTI6MDA6MDBaIiwiaWQiOiJ2dWxuX2FiYzEyMyIsImQiOiJkZXNjIn0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: With Total Count

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?first=20&include_total=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "vulnerabilities": [...],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "start_cursor": "eyJ2IjoxLC...",
    "end_cursor": "eyJ2IjoxLC...",
    "total_count": 6317
  }
}

Iterating All Results

import requests

def get_all_vulnerabilities(api_key):
    url = "https://api.blocksecops.com/api/v1/vulnerabilities"
    headers = {"Authorization": f"Bearer {api_key}"}

    all_results = []
    cursor = None

    while True:
        params = {"first": 100}
        if cursor:
            params["after"] = cursor

        response = requests.get(url, headers=headers, params=params)
        data = response.json()

        all_results.extend(data["vulnerabilities"])

        if not data["page_info"]["has_next_page"]:
            break

        cursor = data["page_info"]["end_cursor"]

    return all_results

---

Offset-Based Pagination (Legacy)

Traditional offset pagination using skip and limit. Supported for backward compatibility.

Parameters

Parameter	Default	Max	Description
skip	0	-	Number of records to skip
limit	100	1000	Maximum records to return

Response Format

{
  "vulnerabilities": [...],
  "total": 6317,
  "page": 1,
  "page_size": 20
}

Example

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?skip=0&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination Through Results

# Page 1
GET /api/v1/vulnerabilities?skip=0&limit=20

# Page 2
GET /api/v1/vulnerabilities?skip=20&limit=20

# Page 3
GET /api/v1/vulnerabilities?skip=40&limit=20

# Page N
GET /api/v1/vulnerabilities?skip=((N-1)*limit)&limit=20

---

Which Style to Use?

Use Case	Recommended Style
Large datasets (1000+ items)	Cursor-based
Real-time data (frequently updated)	Cursor-based
Infinite scroll UI	Cursor-based
Export all data	Cursor-based
Jump to specific page	Offset-based
Simple integrations	Offset-based
Display page numbers	Offset-based

---

Supported Endpoints

Pagination is supported on these list endpoints:

Endpoint	Cursor	Offset
GET /vulnerabilities	Yes	Yes
GET /scans	Yes	Yes
GET /contracts	Yes	Yes
GET /projects	Yes	Yes
GET /audit-logs	Yes	Yes
GET /api-keys	Yes	Yes
GET /organizations	No	Yes

---

Best Practices

1. Use cursor pagination for large datasets - More efficient for 1000+ items
2. Don't include total count unless needed - include_total=true adds latency
3. Use reasonable page sizes - 20-100 items is typical
4. Handle empty results - Check has_next_page before continuing
5. Store cursors, not page numbers - Cursors remain valid as data changes