Important Update to CrowdTangle | March 2024: CrowdTangle will no longer be available after August 14, 2024. Please see our FAQ for more information.
Full API Documentation is available in the CrowdTangle API wiki.
Check out the API Cheat Sheet for best practices.
Welcome to the CrowdTangle API! You can use the CrowdTangle API to access posts, search through CrowdTangle, and access the leaderboard and the link-checker.
If you have access to the API, you can locate your API token via your dashboard under Settings > API Access.
Note: If you are upgrading from the prior version of the API, please see our upgrading release notes.
So What Can You Do With It?
Did you know that two of CrowdTangle's most popular features were made using the CrowdTangle API? The Chrome Extension link checker uses the /links endpoint API to show you all the accounts that have shared a url, and Live Displays use /posts, posts/search and /leaderboard to pull all of the data into a constantly updating livestreaming board.
Partners have used the API in a variety of different ways as well: Some partners use the API to automatically pull CrowdTangle's social data into their internal analytics systems; others use it to fill content sections on their external website; still others have used it as the basis for complex, interactive, consumer-facing features! Check out these examples below:
MTAN: Created a dashboard to track the 2020 Myanmar Elections on their website.
The API also allows you to pull time-series data for posts in bulk, and merged with the post content information.
Remember: The API isn't just Facebook data. We have Facebook, Instagram. We also can send data broken out by the individual post or aggregated by account.
Please note that the below API use cases are forbidden:
Building an external tool, widget or bot that allows the general public to search or otherwise operate inside CrowdTangle. View-only tools are permitted. If you do build this type of tool, you must store data on your own servers, and only call CrowdTangle on a regular pattern.
Integrating CrowdTangle into a product that is for sale.
Selling or giving CrowdTangle data to anyone who does not have or is not eligible for CrowdTangle access.
Getting Started: Authentication
The CrowdTangle API expects the API token to be included either as a custom header with the name x-api-token or as a token query parameter.
// as a custom header
curl "https://api.crowdtangle.com/posts"
-H "x-api-token: your-api-token"
// as a query parameter
curl "https://api.crowdtangle.com/posts?token=your-api-token"
Making a Request
All requests to the CrowdTangle API are made via GET to https://api.crowdtangle.com/. You must use https.
Let's look at some endpoints we have. The main features of the dashboard are replicable. And this is the best way to understand what the API offers.
GET /posts/: Pulls in actual posts from your lists, with the data. The time frame is Last 6 hours by default for the API, but you can change it to match the dashboard.
GET /posts/search: Pulls in the posts from the search queries in your dashboard. The endpoint is pretty powerful, and is not available by default; it must be enabled for you by someone on our team. One thing you'll notice is that it's cross-platform.
GET /leaderboard: Gives you all the data you'd get in a leaderboard, such as interactions, posts per day, video views, and follower counts. Note this does not match the dashboard exactly because it pulls "last 24 hours" by default.
GET /links: Shows you who shared a specific url. This is a convenience endpoint for a more complex search. It'll give you all of the links it finds, up to 100 at a time, and will let you keep paging.
GET /lists: Simply gives you a list of the lists you have in your dashboard, with the ids.
Rate Limits:
Our default rate limits are pretty strict. Why? Our queries are expensive. It's searching, scoring and sorting billions of posts.
What does this mean? Our API is not designed to be called from your system's front end. Rather, all calls should be made from your server and stored. We should not get an API call every time someone hits your app server.
While the command line works, we use this super sophisticated tool called "the browser." Kidding aside, our API works great in the browser and it's a simple way to test it. Get the JSONView Chrome extension for easiest viewing.
Questions? Feedback? Email support@crowdtangle.com