Skip to content

Results navigation

When you interact with the Tweet Binder API, the results you receive can be navigated using three main mechanisms: pagination, filtering, and ordering. This guide explains how to use each of these features to make the most of your data queries.

1. Pagination

Large result sets are paginated to make responses faster and easier to handle. A typical paginated response from the API looks like this:

{
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 100,
    "nextResults": "?offset=1&limit=20"
  },
  "data": [ ... ]
}

Pagination fields explained:

  • offset: The index of the current page (starting from 0).
  • limit: The number of results per page. Defaults to 20 unless otherwise specified.
  • total: Total number of items matching your query.
  • nextResults: A query string to retrieve the next page of results. If there are no more results, this will be null.
  • data: The actual array of documents returned by your query.

To get the next page of results, just take the value of nextResults and use it as your next query string.

2. Filtering Results

You can narrow down your results by applying filters in the query string. There are two types of filters:

A. Pagination Filters

These control how many results you get per page and which page to start from:

  • ?offset=1 — Return results starting from the second page (page numbering starts at 0).
  • ?limit=10 — Return only 10 results per page.

You can combine them: ?offset=2&limit=15

B. Field Filters

You can filter by almost any field in the document. For example:

  • ?status=generated — Only show reports that have already been generated.
  • ?user.name=tweetbinder — Only show documents (e.g., tweets) where the user name is "tweetbinder".

Important: The API is case-sensitive, so tweetbinder is different from TweetBinder.

Advanced filter modifiers:

You can apply special modifiers to enhance your filtering:

Modifier Description Example
lt Less than ?total=lt|100
gt Greater than ?followers=gt|1000
in Match any in list ?status=in|deleted,removed
nin Exclude list ?status=nin|waiting,generated
size Array size match ?hashtags=size|1
regex Regex pattern match ?user.alias=/^celia/
exists Field presence ?user.location=exists|true

You can combine multiple filters to make more precise queries.

3. Ordering Results

You can sort the returned results using the order parameter. The syntax is:

?order=<field>|<direction>
  • Field: The name of the field to sort by (e.g., createdAt, followers, etc.)
  • Direction:
  • 1 = ascending (default)
  • -1 = descending

Example:

  • ?order=createdAt|-1 — Returns the results sorted by creation date, from newest to oldest.
  • ?order=user.followers|1 — Sorts by follower count in ascending order.

Putting It All Together

You can combine pagination, filtering, and ordering in a single query. Here's an example:

?status=generated&user.name=tweetbinder&limit=10&offset=2&order=createdAt|-1

This will return the third page of reports (offset = 2), showing 10 results per page, only for reports with status "generated", created by "tweetbinder", sorted by creation date from newest to oldest.

Summary

  • Use offset and limit for navigating pages.
  • Filter results using field values and modifiers.
  • Sort results using the order parameter.

This flexible system allows you to build very specific queries to retrieve exactly the data you need from the Tweet Binder API.