Pagination & Expands
Testmo's API supports pagination to retrieve large API results in multiple pages (chunks). Many API methods accept pagination parameters so you can request more results with additional API calls.
Testmo's API also supports the concept of expands. When making API calls, responses often include references to related resources. For example, when retrieving a list of test runs, the returned runs include references to related users, configurations or milestones. You can ask Testmo to expand such related resources so that the API responses include these resources directly without sending extra API calls.
Pagination is implemented with two request parameters, namely
page and per_page. pagedetermines the page to return and per_page determines the number of items to return per page:Parameter | Type | Description |
|---|---|---|
 page | integer | Number of page to return (default: first page) |
per_page | integer | Maximum number of items to return (supported: 15, 25, 50, 100; default: 100 |
API methods that support pagination follow the same conventions and always include the following attributes in the response:
Attribute | Type | Description |
|---|---|---|
 page | integer | Number of page returned (or null for an empty result without any pages) |
prev_page | integer | Number of previous page (or null without a previous page) |
next_page | integer | Number of next page (or null without a next page) |
last_page | integer | Number of last page (or null for an empty result without any pages) |
per_page | integer | Maximum number of items returned per page |
total | integer | Total number of items across all pages |
result | array | List of items of the page |
As an example, consider getting the first page of test runs for a project with ID 1:
GET /api/v1/projects/1/runs
If there are more than 100 test runs in the project, a typical response can look as follows:
200 OK
{
"page": 1,
"prev_page": null,
"next_page": 2,
"last_page": 2,
"per_page": 100,
"total": 150,
"result": [
{ "id": 150, "name": "Run 150", .. },
{ "id": 149, "name": "Run 149", .. },
{ "id": 148, "name": "Run 148", .. },
{ "id": 147, "name": "Run 147", .. },
..
{ "id": 51, "name": "Run 51", ..}
]
..
}
The response indicates that we have a total of 2 pages with a total of 150 test runs. To get the second (and last) page, we can simply add the
page parameter to the request as follows:GET /api/v1/projects/1/runs?page=2
Testmo will then return the second page of test runs:
200 OK
{
"page": 2,
"prev_page": 1,
"next_page": null,
"last_page": 2,
"per_page": 100,
"total": 150,
"result": [
{ "id": 50, "name": "Run 50", .. }
{ "id": 49, "name": "Run 49", .. }
{ "id": 48, "name": "Run 48", .. }
{ "id": 47, "name": "Run 47", .. }
..
{ "id": 1, "name": "Run 1", ..}
]
..
}
Important: if
next_page is null or if page equals last_page, the returned page represents the last page of the result set and there are no additional pages to query. When requesting more than one page of items (especially in a loop), please make sure to handle this condition. Otherwise, your API access may be throttled or limited in case you send an unnecessary or excessive amount of requests.Note that most API methods return the most recent items first (i.e. in descending order by creation date). Some API methods support additional parameters to customize this behavior, namely
sort and order. Please refer to the documentation of those API methods for details.Expands are supported by many Testmo API methods and make it easy to include referenced related resources in API results. This is helpful to simplify API access and to reduce the number of API calls you need to make. You can tell API methods to return such expands in the response by including an
expands request parameter as a comma-separated list of object types.An an example, to include referenced configurations, milestones and users when retrieving a page of test runs, you can include an
expands parameter as follows:GET /api/v1/projects/1/runs?expands=configs,milestones,users
Testmo will then include the expands as part of the
expands attribute in the result:200 OK
{
"page": 2,
"prev_page": 1,
"next_page": null,
"last_page": 2,
"per_page": 100,
"total": 150,
"result": [
{
"id": 150,
"name": "Run 150",
"config_id": 10,
"milestone_id": 5,
"created_at": "..",
"created_by": 2,
"closed_at": "..",
"closed_by": 1
},
..
],
"expands" {
"configs": [
{ "id": 10, "name": "Chrome" },
..
],
"milestones": [
{ "id": 5, "name": "Release 1.0" },
..
],
"users": [
{ "id": 1, "name": "User 1" }, // For closed_by
{ "id": 2, "name": "User 2" }, // For created_by
..
]
}
}
Depending on the API method, Testmo supports the following types of expands:
automation_sourcesconfigsfield_valuesgroupsissuesmilestone_statsmilestone_typesmilestonesrolesstatesstatusestemplatesusers
Most expand types support the
id and name attributes and some expand types also include additional attributes. You can find a full list of supported attributes in the OpenAPI schema.Last modified 2d ago