The CrowdTangle API corresponds to several functions available through the Dashboard. It’s as if you were directly obtaining a CSV of your List or Saved Search, but in JSON or XML format. Please note that we don't have all filters available in the new Search surface in the API yet, but all the same posts are available.

Postman is a free API management software. Click here to download a JSON file that you can import into Postman (unzip the file to access), and get a template for each endpoint. Please note that not all parameters are present in the template; please view the Github API documentation to explore all parameter options.

Check out our full API documentation on GitHub. Make all API rate limit and feature access requests using this form.

*Please note that on October 20, 2020, we will be changing the structure of CrowdTangle Post IDs. Read this article to ensure that your API tools are ready to accommodate this change.*

Some helpful tips for getting the best API experience:

For all endpoints, use the start date and end date parameters to prevent CrowdTangle from crashing and to reduce load times.

Use a Facebook Dashboard token to call Facebook posts, and an Instagram Dashboard token to call Instagram posts -- you unfortunately can't use the same token across different platforms.

Number of posts returned and pagination

  • /posts and /posts/search will max out at 10,000 posts returned. /links will max out at 1000 posts returned. You must paginate through those posts to reach the end of the query,
  • You can see up to 100 posts at a time (count parameter goes up to 100). To see the next one hundred posts, paginate using the offset parameter. For example: set count = 100 to see posts 1-100. Then, set count = 100 and offset = 100 to see posts 101 - 200. Continue increasing the offset parameter in successive calls to see all posts.
  • Each pagination will count against your rate limit. Slice thinly by date or SQL timeframe to separate your results into ~10k batches so you don't miss any data. To get more than 10k posts at a time, use Historical Data in the Dashboard rather than the API.
  • To calculate the number of posts that will be returned for a given call, fill out this form to request activation of the hitCount setting. When hitCount is activated and you set count=0 for any query, the response will return the number of results. Then, you can divide this number by 10,000 to calculate the number of queries you'll need to make to obtain all the data.

Making sure you get all posts for a given time period

  • Make sure to sort by Date to capture all posts. If you don’t specify the sort parameter, the API will by default return posts sorted by Overperforming. This will exclude posts that are Underperforming.

Default rate limits and settings:

  • /posts/search is not enabled by default. We can enable it for you based on the use case -- just fill out this form.
  • Rate limit defaults: 6 calls/min for all but /links, which is 2 calls/min. We can raise your rate limit depending on the use case -- just fill out the API request form.
  • By default, the API object names do not match the CSV headers. We can now match your CSV download headers to the API object names. Please request activation for this feature either when you're filling out an API form for another reason, or by emailing support@crowdtangle.com.
  • The API uses the UTC timezone. This cannot be changed. The CrowdTangle User Interface allows the user to change the time zone of their dashboard, so always account for time zone differences when comparing results in the API and UI.

Endpoints Overview

/posts

  • This endpoint lets you stream data from posts in a List or Saved Search. It’s as if you were looking at a List or Saved Search in your Dashboard. It does not let you search the entire CT database.
  • You can search for terms within the List or Saved Search using Boolean syntax with the SearchTerm parameter.
  • Make sure to grab your List ID from the URL or the /lists endpoint in order to pull in posts -- this ID exists for both Lists and Saved Searches.
  • You can use Weights just like in a List or Saved Search in the Dashboard, on a scale of 1-10
  • The default number of posts returned at a time is 10. The count parameter can only go to between 1-100 -- paginate using the offset parameter to view all posts. 
  • Use the includeHistory parameter to get timesteps for each post -- this is the same data as when you download a single post CSV in the UI.

/post/:id

  • Retrieves a specific post according to its Facebook ID. Read more about the endpoint here.
  • Use the includeHistory parameter to get timesteps for the post -- this is the same data as when you download a single post CSV in the UI.

/ctpost/:id

  • Retrieves a specific post according to its CrowdTangle ID. Read more about the endpoint here. 
  • Use the includeHistory parameter to get timesteps for the post -- this is the same data as when you download a single post CSV in the UI.

/posts/search

  • This endpoint acts like Historical Data, but with more nuanced search terms. It lets you search the entire CT database. You can differentiate account types using the accountTypes parameter.
  • The SearchField parameter allows you to search for URLs with query strings, image text only, and account names, in addition to the usual post text and image text.
  • /posts/search does not support regular expressions, or any sort of wildcard search.
  • You can pull in from Lists and Saved Search by using the ListID parameter, just like in the /posts endpoint. You can also pull in from Account using AccountID parameter.
  • You can use "OR," “AND” and “NOT” for terms and Lists to search, but you cannot use Weights. Request activation of Boolean search for the SearchTerm parameter by filling out the API request form.
  • Most of the functionality you’d want from this is easily available by setting up a Saved Search in your Dashboard, and pulling it in through the /posts endpoint.
  • The default number of posts returned at a time is 10. The count parameter can only go to between 1-100 -- paginate using the offset parameter to view all posts. 
  • Use the includeHistory parameter to get timesteps for each post -- this is the same data as when you download a single post CSV in the UI.

/leaderboard

  • This acts like Lists Leaderboard -- NOT Search Leaderboard. You will not get a list of the number of posts that match your search parameters through this endpoint.

/links

  • This endpoint acts like the Chrome Extension. However, it will pull in Facebook, Instagram and Reddit, but not Twitter, even though Chrome Extension does.
  • You can specify the number of posts to pull in - the maximum is 1000. 
  • Set the summary parameter to “true” to get the top-line summary of interactions for the link.
  • Use the includeHistory parameter to get timesteps for each post -- this is the same data as when you download a single post CSV in the UI.
  • The SearchField parameter allows you to search for URLs with query strings.

/lists

  • This endpoint tells you the names and IDs of all your Lists. This allows you to quickly pull List IDs for inclusion or exclusion in queries with other endpoints.

/lists/:listId/accounts

  • This endpoint tells you the names of all the Pages or Groups in a given List.  This allows you to quickly pull Account IDs for inclusion or exclusion in queries with other endpoints.

 
For more information, please see this broader overview of the API, and check out our API documentation on GitHub.

Did this answer your question?