Introduction
To keep the Perfect Gym API fast and stable, every API V2 endpoint returns only a limited number of records per request. This article explains the limits and how to work with them.
- This article is for developers and integration partners who use the Perfect Gym API V2 (OData endpoints).
- After reading it, you will know how many records each endpoint returns per request, what happens when you ask for more, and how to retrieve a full data set page by page.
The limits described here apply to API V2.0, V2.1 and V2.2.
Before you start
- You need access to the API and a way to authenticate. See API - Authentication.
Feature description
What is the record limit?
Each API V2 OData endpoint returns a limited number of records per request. Most endpoints return up to 500 records. A few endpoints use a different limit. For example, the Members endpoint returns a maximum of 100 records.
Limits keep the API fast and stable. Without them, a single request could ask for a very large number of records and slow the system down for everyone. The limit also applies when you do not send $top: the API then returns one page, not the whole data set.
What happens when you ask for more than the limit?
If a request asks for more records than the endpoint allows, the API rejects it with an error like this:
{
"error": {
"code": "",
"message": "The query specified in the URI is not valid. The limit of '100' for Top query has been exceeded. The value from the incoming request is '500'."
}
}To retrieve more records than the limit, request the data in several pages. See How to retrieve more records with pagination in the API?
Which endpoints have which limit?
Quick comparison
| Limit | Endpoints |
|---|---|
| 100 | 12 endpoints (see the first table below) |
| 500 | All other endpoints (standard limit) |
| 1000 | ClassBookings |
Lower limit: 100 records per request
| Endpoint | Area | Note |
|---|---|---|
| Members | Members | |
| MemberRelations | Members | |
| ContractFreezes | Contracts | |
| CashlessDebitPosTransactions | Transactions | |
| CrmLeads | CRM | |
| CrmLeadSources | CRM | |
| Crm2Leads | CRM 2 | |
| Crm2Events | CRM 2 | V2.1 and V2.2 only |
| Crm2ConsultantAvailability | CRM 2 | V2.1 and V2.2 only |
| PersonalTrainingBookingDetails | Personal training | |
| States | Geo | |
| Cities | Geo |
Higher limit: 1000 records per request
| Endpoint | Area | Note |
|---|---|---|
| ClassBookings | Classes |
Standard limit: 500 records per request
All other OData endpoints use the standard limit of 500. Some endpoints state this limit explicitly: Classes, ClassTypes, ClassCategories, MemberClubVisits, ContractCharges and CustomAttributeDefinitions.
Instruction
How to retrieve more records with pagination in the API?
Pagination means requesting the data in pages and repeating the request until you have everything. You can use one of two options.
Option 1: $top and $skip
- Send the first request with
$topset to the endpoint's limit,$skip=0and an$orderby, so that the order is the same on every page. Add$count=trueto receive the total number of records. - For each next request, increase
$skipby the page size. - Stop when a response returns fewer records than the page size.
GET /api/v2.2/odata/Members?$top=100&$skip=0&$orderby=id&$count=true
GET /api/v2.2/odata/Members?$top=100&$skip=100&$orderby=id
GET /api/v2.2/odata/Members?$top=100&$skip=200&$orderby=idExample loop (pseudocode):
skip = 0
do
page = GET /Members?$top=100&$skip={skip}&$orderby=id
process(page.value)
skip += 100
while page.value.count == 100Option 2: @odata.nextLink
- Send your first request.
- When more records are available, the response may include an
@odata.nextLinkURL. Call that URL unchanged to get the next page. - Stop when a response has no
@odata.nextLink.
How to test a limit in the API?
-
Send a request above the limit. It should be rejected with the error shown above:
GET /api/v2.2/odata/ContractFreezes?$top=500 GET /api/v2.2/odata/CashlessDebitPosTransactions?$top=500 -
Send a request at the limit. It should succeed:
GET /api/v2.2/odata/ContractFreezes?$top=100&$orderby=id&$count=true
Hints
- Use the same
$orderbyand$filterfor every page of one run. - Use
$filterto reduce the data, for exampleisActive eq trueon Members. - Do not send a
$topabove the limit for the endpoint. - Limits are per request. Calling more often does not raise the limit, and very frequent calls may be rate limited.
- For more ways to make your requests faster, see Optimizing OData API Performance.
- For other error messages returned by the API, see API - errors.
- If you need help, contact Perfect Gym Support and include the request URL, the response and the API version you use.
Note: This article was created with the help of artificial intelligence and editorially reviewed.