Full API Documentation available here: CrowdTangle API wiki
Watch a full training session on our API, with our developer George. (~30m)
Welcome to the CrowdTangle API! You can use the CrowdTangle API to access posts, the leaderboard and the link-checker. Please contact your CrowdTangle representative for access.
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.
To get started, here's a handy Beginner's Guide to the CrowdTangle API from our partner Nate Harris, along with a Google Sheets workbook with instructions on pulling the data into Google Data Studio.
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:
- The Philadelphia Inquirer: Pulls Twitter data for their reporters into their owned and operated analytics system.
- 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, Twitter* and Reddit. We also can send data broken out by the individual post or aggregated by account.
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 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.
*The Twitter caveat: Because of the Twitter API's terms and conditions, we can't send anything in our API that they're already sending in theirs (e.g., account name or handle, number of retweets, etc). What we can do is send any calculated scores (overperforming or leaderboard aggregates) and the requisite information (Twitter IDs, etc) — that you'll need to grab the rest of the info from the Twitter API itself.
To learn more, watch a full training session on our API, with our developer George.
Questions? Feedback? Email support@crowdtangle.com
Webinars: Sign up for the next training session!