Responses

HTTP Status code

Successful requests

Code	Message	Details
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.

Failed requests

Code	Message	Details
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 Allow header.
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.

Server errors

Code	Message	Details
500	Internal Server Error	Unexpected internal server error.
503	Service Unavailable	The server is not running.

Base response

All API responses are json objects, with the application/json content type. They contains one or more data field and a status field.

For example, a query to get a Category ressource returns this kind of response:

{
  "category": {
    "id": "12",
    "name": "Politics"
  },
  "status": {
    "cost": 1,
    "apiDeprecationNotice": {
      "message": "The version 1 of the API is deprecated and will be shut down the 2022-02-02 at 00:00:00 UTC.",
      "shutdownDate": "2022-02-02T00:00:00.000Z"
    }
  }
}

The 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.

Partial resources

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.

Pagination

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.

caution

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 unpredictable.

caution

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:

{
  "items": [
    {
      "id": "12",
      "name": "string"
    }
  ],
  "pagination": {
    "self": "string",
    "prev": "string",
    "next": "string"
  },
  "status": {
    "cost": 0
  }
}

Live data

Data collected by Exorde is immediately available for querying. However, the last hour of data is not guaranteed to be 100% accurate. It's not fully consolidated and may be subject to change as new posts are added to the system. For example, the number of posts or the sentiment of a topic in the last hour can change.

Generally, data is accurate after 20 minutes. But you should be very careful when using the last 5 minutes of data, as can have too low volume to be representative of the real situation.

Data older than 1 hour is fully consolidated and will not change anymore.

Here is an example of the volume of posts over the last hour:

Time series

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. Each data point contains a start and end date, according to re requested granularity.

Time bucketing

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:07:00Z to 2023-05-01T15:23:00Z with 5 minutes granularity, the response will contains the following data points:

• 2023-05-01T15:05:00Z to 2023-05-01T15:10:00Z period
• 2023-05-01T15:10:00Z to 2023-05-01T15:15:00Z period
• 2023-05-01T15:15:00Z to 2023-05-01T15:20:00Z period

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-01T00:00:00Z to 2023-05-02T00:00:00Z period, the response can be:

[
  {
    "metric": 42,
    "postsCount": 4906,
    "startDate": "2023-05-01T09:00:00.000Z",
    "endDate": "2023-05-01T10:00:00.000Z"
  },
  {
    "metric": null,
    "postsCount": 0,
    "startDate": "2023-05-01T10:00:00.000Z",
    "endDate": "2023-05-01T11:00:00.000Z"
  },
  {
    "metic": 56,
    "postsCount": 1423,
    "startDate": "2023-05-01T11:00:00.000Z",
    "endDate": "2023-05-01T12:00:00.000Z"
  }
]

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-01T10:00:00.000Z and 2023-05-01T11:00:00.000Z, so the response contains a data point for this period.

Errors

Client error

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:

{
  "error": {
    "message": "An error occurred.",
    "code": 100,
    "userId": "123e4567-e89b-12d3-a456-426655440000",
    "requestId": "123e4567-e89b-12d3-a456-426655440000"
  },
  "status": {
    "cost": 0
  }
}

Server error

Server error are responses with the HTTP status code 5xx. The response can be a request id or no body.