Full API Documentation is available in the CrowdTangle API wiki.
Check out the API Cheat Sheet for best practices.
Watch a full training session on our API, with our developer George. (~30m)
*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.*
Welcome to the CrowdTangle API! You can use the CrowdTangle API to access posts, the leaderboard and the link-checker. To request access, please fill out this form.
If you have access to the API, you can locate your API token via your dashboard under Settings > API Access. The CrowdTangle API is currently in a private beta, which means that while you can expect endpoints and parameters to remain stable, but there will be other changes happening frequently.
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:
- Patch: Easily curates community content for their sites.
- SVT: Powered an interactive feature on the Swedish election for their site.
Remember: The API isn't just Facebook data. We have Facebook, Instagram and Reddit. 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
-H "x-api-token: your-api-token"
// as a query parameter
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.
- Our 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.
To learn more, watch a full training session on our API, with our developer George.