API Reference

Pagination

Every list endpoint in the Pineprompt API paginates its results using a shared envelope. Pagination is page-number-based, with an optional per_page parameter to control the size of each page.

Query parameters

You may control pagination using two query parameters. Both are optional.

Name Type Required Description
per_page integer Optional

The number of items to return on each page. Defaults to 25, with a minimum of 1 and a maximum of 100. Values outside this range are silently clamped.
page integer Optional

The page number to return, starting at 1. A page beyond the last will return an empty data array rather than an error.

The response envelope

Every paginated response carries the records under data, alongside links and meta for navigation:

{
  "data": [ /* records */ ],
  "links": {
    "first": "https://pineprompt.com/api/v1/monitors?page=1",
    "last":  "https://pineprompt.com/api/v1/monitors?page=3",
    "prev":  null,
    "next":  "https://pineprompt.com/api/v1/monitors?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://pineprompt.com/api/v1/monitors",
    "per_page": 25,
    "to": 25,
    "total": 72
  }
}

Pagination metadata

The meta object describes the page you received and the collection as a whole.

Field Type Description
current_page integer

The page number you are currently viewing, starting at 1.
from integer

The index of the first record on this page within the full collection, or null when the page is empty.
last_page integer

The number of the final page.
path string

The base URL of the endpoint, without any query string.
per_page integer

The number of records requested per page.
to integer

The index of the last record on this page within the full collection, or null when the page is empty.
total integer

The exact number of records across every page.
links PaginationLink[]

The page-link rows, in display order from the first page through the last. The set always opens with a previous link and closes with a next link.

Walking every page

Typically, the simplest way to iterate every record is to follow links.next until it becomes null:

Example

JavaScript (fetch) javascript 
async function* paginate(url, headers) {
  let next = url;
  while (next) {
    const response = await fetch(next, { headers });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    const payload = await response.json();
    yield* payload.data;
    next = payload.links.next;
  }
}

const headers = {
  "Authorization": `Bearer ${process.env.PINEPROMPT_TOKEN}`,
  "Pineprompt-Project-Id": "42",
};

for await (const monitor of paginate("https://pineprompt.com/api/v1/monitors?per_page=100", headers)) {
  console.log(monitor.id);
}
Python (requests) python 
import os, requests

headers = {
    "Authorization": f"Bearer {os.environ['PINEPROMPT_TOKEN']}",
    "Pineprompt-Project-Id": "42",
}

url = "https://pineprompt.com/api/v1/monitors?per_page=100"
while url:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    payload = response.json()
    for monitor in payload["data"]:
        print(monitor["id"])
    url = payload["links"]["next"]
PHP (Guzzle) php 
use GuzzleHttp\Client;

$client = new Client();
$url = 'https://pineprompt.com/api/v1/monitors?per_page=100';
$headers = [
    'Authorization' => 'Bearer '.getenv('PINEPROMPT_TOKEN'),
    'Pineprompt-Project-Id' => '42',
];

while ($url) {
    $response = $client->get($url, ['headers' => $headers]);
    $payload = json_decode((string) $response->getBody(), true);

    foreach ($payload['data'] as $monitor) {
        echo $monitor['id'].PHP_EOL;
    }

    $url = $payload['links']['next'] ?? null;
}

A few notes

  • For bulk backfills, you should set per_page=100. Larger pages mean fewer round-trips, and the rate-limit cost is identical regardless of page size.
  • The meta.total field is an exact total. On very large collections, computing it carries a cost, so if you only need to walk the list, you may safely ignore it.
  • The non-paginated projects array inside GET /me is the only collection that does not use this envelope.