HTTP Status code
|200||Success||Success with response body.|
|201||Created||Success with response body.|
|204||Success||Success with no response body.|
|301||Moved Permanently||The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.|
|400||Bad Request||The request is not valid, it can be due to a missing header/parameter, a syntax error or a schema violation.|
|401||Unauthorized||The user is not authorized to use the API.|
|403||Forbidden||The requested operation is not permitted for the user.|
|404||Not Found||The requested resource was not found. This can be caused by an ACL constraint or if the resource does not exist.|
|405||Method Not Allowed||The HTTP action is not allowed for the requested API endpoint. Allowed methods are returned in the |
|429||Too Many Requests||The API Key's rate limit was exceeded. It can be an HTTP request throttling error or the monthly API call credit limit that is reached.|
|500||Internal Server Error||Unexpected internal server error.|
|503||Service Unavailable||The server is not running.|
All API responses are json objects, with the
application/json content type. They contains one or more data field and a
For example, a query to get a
Category ressource returns this kind of response:
"message": "The version 1 of the API is deprecated and will be shut down the 2022-02-02 at 00:00:00 UTC.",
status object always contains the cost of the API call. But the deprecation fields are only returned when a deprecated endpoint or API version is called.
By default the API does not always return the full resources representation. Only most importants fields are returned by default. You can ask for more fields, or even all fields using the query parameter
additionalFields. When an endpoint returns partial result, it's clearly indicated in the API Reference and the list of all available fields is given.
Fields that are always returned are marked as required in the response schema.
Some endpoints does not return a resource but a list of resources. These endpoints use cursor based pagination to iterate over the collection.
When you first call a paginated endpoint, it will send pagination links in the response to let you ask for the previous or the next results. These links are ready to use, they contain the cursor and all required query parameters.
You can iterate while the next/previous is present in the response. When the link is missing, this indicates there are no further records and you should stop paginating. The last page may be empty, this occurs when the previous page returned a full record set. In this case, there are no pagination links in the response.
A paginated response contains the following links:
- self: Pagination link pointing to the current page.
- prev: Pagination link pointing to the previous page. This link is not present if there is no previous page.
- next: Pagination link pointing to the next page. This link is not present if there is no next page.
You should not try to forge or edit a pagination URL manually but rely on the link provided. If the pagination link is modified, the response will be unpredicable.
Paginated data may be inaccurate due to the addition, removal, or modification of records while you're paginating through the list.
For example, a query to list the
Category resources returns this kind of response:
Some endpoints return time series response that can be used to draw charts. These responses contains data points that represent the evolution of the data over time, with the requested granularity.
The data granularity must be the same for the entire response, if the requested granularity is higher than the lowest available granularity for the dataset, this lower granularity is used instead.
The requested granularity and the actual granularity are both sent in the response. Also, each data point contains a start and end date.
Each time series endpoint has its own granularity and data retention. Refer to endpoint's documentation to know what granularities are available.
Time buckets in the response are calculated from
1970-01-01T00:00:00Z. For example, if you request a time series from
2023-05-01T15:23:00Z with 5 minutes granularity, the response will contains the following data points:
In each bucket, the lower bound is inclusive and the upper bound is exclusive, so the data with timestamp
2023-05-01T15:10:00Z is included in the second period of the example.
The request parameter
startDate is inclusive, the bucket containing it is always included in the response. The actual
startDate is aligned with the beginning of the bucket containing it.
The request parameter
endDate is exclusive, the bucket containing it is never included in the response. The actual
endDate is aligned with the end of the previous bucket.
Empty data points
Periods without data are included in the response if there are data points before and after the period. In this case, the metric value will be set to
null and the posts count will be set to 0. Periods without data that lie completely outside the data interval are not included.
For example, if you request a time series for the
2023-05-02T00:00:00Z period, the response can be:
In this example, there is no data before
2023-05-01T09:00:00.000Z and after
2023-05-01T12:00:00.000Z, so the response does not contains data points for these periods. But there is a period without data between
2023-05-01T11:00:00.000Z, so the response contains a data point for this period.
Client error are responses with the HTTP status code
4xx. The response contains an
error field giving information about the error with an error code and an error message. The error code can be an error specific code or the HTTP status code (by default). The error message helps to find the cause of the error. For example, a
400 Bad request error will give the wrong or missing fields in the error message.
The error body has the following shape:
"message": "An error occured.",
Server error are responses with the HTTP status code
5xx. The response can be a request id or no body.