Skip to main content

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}
Varies By Endpoint

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.

Example of Cursor-Based Pagination​

Imagine you have a collection of 500 Nodes stored in the database, and you can want retrieve 10 Nodes at a time:

Get First 10 Nodes Request​

You request the first 10 Nodes.

GET /api/v1/environments/{environmentID}/nodes?limit=10

Get First 10 Nodes Response​

You get 10 Nodes plus a cursor pointing to the Node ID where you left off in next.

{
  "data": [
    {
      "database": "sales",
      "id": "27",
      "locationName": "US-East",
      "name": "Region",
      "nodeType": "Dimension",
      "schema": "public"
    },
  ],
  "total": 500,
  "limit": 10,
  "next": "eyJpZCI6IjMzIn0", //where you left off
  "orderBy": "id"
}

Get Next 10 Nodes Request​

You ask for the next 10 Nodes, starting after your cursor. The limit=10 and startingFrom=eyJpZCI6IjMzIn0. startingFrom only returns in the response, if the query parameter is passed in.

GET /api/v1/environments/{environmentID}/nodes?limit=10&startingFrom=eyJpZCI6IjMzIn0

Get Next 10 Nodes Response​

You get the next 10 Nodes plus an updated cursor, "next": "JpZCI6IjE3OCJ9"

{
  "data": [
    {
      "database": "sales",
      "id": "27",
      "locationName": "US-East",
      "name": "Region",
      "nodeType": "Dimension",
      "schema": "public"
    },
  ],
  "total": 500,
 "startingFrom": "eyJpZCI6IjMzIn0",
  "limit": 10,
  "next": "JpZCI6IjE3OCJ9", //where you left off
  "orderBy": "id"
}

Query Parameter Example​

Here is an example of using query parameters.

Using limit and startingFrom​

These examples use the Workspace endpoint to demonstrate limit, startingFrom, and next.

Limit to first 25 Nodes

GET /api/v1/workspaces/{workspaceID}/nodes?limit=25

Response with next the Node after first 25

{
    "data": [
        //... 25 Nodes
    ],
  "total": 142,
  "limit": 25,
  "next": "eyJpZCI6IjEyOCJ9",
  "orderBy": "id"

  
}

Get the Next 25 Workspace Nodes using startingFrom.

Using the value in next, add it to startingFrom to start from Node ID, eyJpZCI6IjEyOCJ9.

GET /api/v1/workspaces/{workspaceID}/nodes?limit=25&startingFrom=eyJpZCI6IjEyOCJ9

Using orderBy and startingFrom​

This will return them by runStartTime and sort them from most recent to the oldest(desc).

GET /api/v1/runs?orderBy=runStartTime&orderByDirection=desc

Next Is Null​

When the response has "next": null, you've reached the end of the results.

{
    "data": [],
    "total": 0,
    "startingFrom": "eyJpZCI6IjEyOCJ9",
    "limit": 2,
    "next": null,
    "orderBy": "id"
}