Query Parameters
Our API provides a flexible way to retrieve data through query parameters. This guide explains the available query parameters and how to use them effectively.
Endpoints
Query parameters are available on the following endpoints:
- GET
/api/v1/environments
- GET
/api/v1/environments/{environmentID}/nodes
- GET
/api/v1/workspaces/{workspaceID}/nodes
- GET
/api/v1/runs
- GET
/api/v1/runs/{runID}
Review each endpoint for available parameters.
What Is Cursor-Based Pagination?
Cursor-based pagination is like using a bookmark in a large dataset. Instead of asking for a specific page number, you are asking to "show me results that come after this point."
Our endpoints offer this using startingFrom
.
When using startingFrom
, you must also include the orderBy
parameter to define the sort order used for the cursor.
Example of Cursor-Based Pagination
Imagine you have a collection of 500 Nodes in the database, and you want to retrieve 10 Nodes at a time:
Get First 10 Nodes Request
GET /api/v1/environments/{environmentID}/nodes?limit=10&orderBy=id
Get First 10 Nodes Response
You get 10 Nodes and a cursor value in the next
field, which points to where you left off.
{
"data": [
{
"database": "sales",
"id": "27",
"locationName": "US-East",
"name": "Region",
"nodeType": "Dimension",
"schema": "public"
}
],
"total": 500,
"limit": 10,
"next": "eyJpZCI6IjMzIn0",
"orderBy": "id"
}
Get Next 10 Nodes Request
Use the next
value in the startingFrom
parameter and include the same orderBy
.
GET /api/v1/environments/{environmentID}/nodes?limit=10&startingFrom=eyJpZCI6IjMzIn0&orderBy=id
Get Next 10 Nodes Response
{
"data": [
{
"database": "sales",
"id": "39",
"locationName": "US-West",
"name": "Territory",
"nodeType": "Dimension",
"schema": "public"
}
],
"total": 500,
"startingFrom": "eyJpZCI6IjMzIn0",
"limit": 10,
"next": "eyJpZCI6IjE3OCJ9",
"orderBy": "id"
}
Using the next
Field
When paginating, the next
value in the response allows you to fetch the next set of results. To do this:
- Copy the
next
value from the response. - Pass it as the
startingFrom
value in your next request. - Always include the same
orderBy
value used in the previous request.
Query Parameter Example
Here are a few examples of using query parameters.
Using limit
, startingFrom
, and orderBy
These examples use the Workspace endpoint to demonstrate paginated requests.
Get the first 25 Nodes
GET /api/v1/workspaces/{workspaceID}/nodes?limit=25&orderBy=id
Response with next
{
"data": [ /* 25 Nodes */ ],
"total": 142,
"limit": 25,
"next": "eyJpZCI6IjEyOCJ9",
"orderBy": "id"
}
Get the next 25 Nodes
GET /api/v1/workspaces/{workspaceID}/nodes?limit=25&startingFrom=eyJpZCI6IjEyOCJ9&orderBy=id
Using orderBy
with Sort Direction
This returns runs sorted by runStartTime
from most recent to oldest.
GET /api/v1/runs?orderBy=runStartTime&orderByDirection=desc
When next
Is Null
If "next": null
, you've reached the end of the dataset.
{
"data": [],
"total": 0,
"startingFrom": "eyJpZCI6IjEyOCJ9",
"limit": 2,
"next": null,
"orderBy": "id"
}