Pagination

The Verdantly API returns paginated responses for all list endpoints. This guide covers the two pagination strategies available and the limits in place.

Offset pagination

Offset pagination is the default strategy for all endpoints. Use the page and perPage query parameters to control which slice of results you receive.

Query parameters

Name
page
Type
integer
Description
The page number to return. Starts at 1, max 100. Defaults to 1.
Name
perPage
Type
integer
Description
Number of items per page. Min 1, max 100. Defaults to 10.

Response meta object

Every paginated response wraps results in a standard envelope with a meta object:

Name
totalCount
Type
integer
Description
Total number of items matching your query across all pages.
Name
page
Type
integer
Description
The current page number.
Name
perPage
Type
integer
Description
The number of items per page.
Name
pages
Type
integer
Description
Total number of pages available.

Request

GET

/v1/plants/varieties/search?q=tomato&page=2&perPage=5

curl -G "https://verdantly.p.rapidapi.com/v1/plants/varieties/search?q=tomato&page=2&perPage=5" \
  -H "X-RapidAPI-Host: verdantly.p.rapidapi.com" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Cherokee Purple Tomato",
      "category": "vegetable",
      "type": "tomato"
      // ... more fields
    }
    // ... 4 more items
  ],
  "meta": {
    "totalCount": 198,
    "pages": 40,
    "page": 2,
    "perPage": 5
  }
}

Cursor pagination is available on variety endpoints as an alternative to offset pagination. Instead of specifying a page number, you pass a cursor value from the previous response. This is more efficient for iterating through large datasets because it avoids the performance cost of deep offsets.

Query parameters

Name
cursor
Type
string
Description
An opaque cursor string from a previous response's meta.nextCursor. Omit on the first request.
Name
perPage
Type
integer
Description
Number of items per page. Min 1, max 100. Defaults to 10.

Response meta object

Name
nextCursor
Type
string | null
Description
The cursor to pass in the next request. null when there are no more results.
Name
perPage
Type
integer
Description
The number of items per page.
Name
totalCount
Type
integer
Description
Total number of items matching your query.

You cannot use cursor and page together. If both are provided, the API will return a 400 Bad Request error.

First request

GET

/v1/plants/varieties/search?q=pepper&perPage=3

curl -G "https://verdantly.p.rapidapi.com/v1/plants/varieties/search?q=pepper&perPage=3" \
  -H "X-RapidAPI-Host: verdantly.p.rapidapi.com" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "b2c3d4e5-...",
      "name": "California Wonder Pepper",
      "category": "vegetable",
      "type": "pepper"
    }
    // ... 2 more items
  ],
  "meta": {
    "totalCount": 87,
    "perPage": 3,
    "nextCursor": "eyJpZCI6ImIyYzNkNGU1LSIsInNjb3JlIjo0Ljd9"
  }
}

Anti-scraping limits

The Verdantly API enforces pagination depth limits to protect the dataset and ensure fair access for all users.

Name
Max page depth
Type
100
Description
The page parameter cannot exceed 100. Requests for page 101+ return a 400 Bad Request error.
Name
Max perPage
Type
100
Description
The perPage parameter cannot exceed 100. This means a single query can access at most 10,000 items (100 pages x 100 items).

These limits exist to prevent bulk scraping of the dataset. If you need access to the full dataset for research or enterprise use, contact us about a data licensing arrangement.

For large result sets, use cursor pagination instead of deep offsets. Cursor pagination does not have a page depth limit and performs consistently regardless of how far into the dataset you are.

400 Response — page too deep

{
  "statusCode": 400,
  "message": "Page number exceeds the maximum allowed depth of 100.",
  "error": "Bad Request"
}

400 Response — perPage too high

{
  "statusCode": 400,
  "message": "perPage cannot exceed 100.",
  "error": "Bad Request"
}