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 filters that correspond with the new Search surface in the API yet, but all the same posts are available.

Postman is a free API software. Click here to download a JSON file that you can import into Postman, and get a template for each endpoint.

Check out our full API documentation on GitHub.

Some helpful tips for getting the best API experience:

  • 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.
  • For all endpoints, use the start date and end date parameters to prevent CrowdTangle from crashing and to reduce load times.
  • 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 by date 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.
  • /posts/search will max out at 10,000 posts returned. /links will max out at 1000 posts returned. Every other endpoint will return the full number of posts that match your query as you paginate through the results. 
  • 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. Make sure to sort by date to capture all posts.
  • /posts/search is not enabled by default. We can enable it for you based on the use case -- just fill out this form.
  • 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.
  • Rate limits: 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 this form.

 

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.
  • 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, and will always pull in BOTH pages/profiles and groups. There is no way to differentiate. 
  • The SearchField parameter allows you to search for URLs with query strings, image text only, 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 filling 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. 
  • 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.
  • 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.
  • This will pull in Facebook, Instagram and Reddit, but not Twitter, even though Chrome Extension does. 
  • 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.

/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?