Skip to main content
GET
Targeting X/Twitter? Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:

X-Twitter-OAuth1-Api-Key — Your API Key (Consumer Key)
X-Twitter-OAuth1-Api-Secret — Your API Key Secret (Consumer Secret)

One-time setup per Ayrshare account. You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do not create a new app per customer.

Not linked yet? See the full setup guide to connect your X account.

Your keys are never logged or stored by Ayrshare.
This endpoint allows you to fetch both posts and their analytics from major social networks (Bluesky, Facebook, Instagram, LinkedIn, Pinterest, Threads, TikTok, X/Twitter, and YouTube). It works for all posts on these platforms - whether they were created using Ayrshare’s API or posted directly through the social network’s interface. More detailed analytics are available with the analytics endpoint. The IDs returned in from this endpoint are the social networks’ native social post ID and not the Ayrshare post ID. This allows you to get details for any post on a social network, even if it was not created through Ayrshare. For example, you can retrieve a post that was manually published on facebook.com and use the Facebook Social Post ID returned to get comments or get analytics. If you do not need posts that originated outside of Ayrshare, simply use the Ayrshare post ID returned in a post with the comment, analytics, or history endpoints. :platform = bluesky, facebook, instagram, linkedin, pinterest, snapchat, threads, tiktok, twitter, youtube. Example: https://api.ayrshare.com/api/history/instagram

​
Copyrighted Media

Instagram and TikTok will exclude all copyrighted media in their responses.
  • The Instagram mediaUrl field is omitted from response if the media contains copyrighted material or has been flagged for a copyright violation. Examples of copyrighted material can include audio on reels. You can check in the Instagram app under Settings -> Account Status.
  • TikTok does not return media if the media contains copyrighted material or has been flagged for a copyright violation. Examples of copyrighted material can include audio on reels (TikTok will mute these videos). You can check in the TikTok app under Activity -> System Notifications.If such a video is muted, you can add audio in the TikTok app. Go to the post and select the option to add non-copyrighted audio. The video will then be returned in this API response.

​
Limitations

​
Facebook

  • Expired/archived Stories (older than 24 hours) are automatically filtered out. Only active Stories are included in the response by default.
  • Use the dataType query parameter to request only posts or only stories.
  • Use the since and until query parameters to filter posts by date range.

​
Instagram

  • Responses will not include Live Video stories.
  • Stories are only available for 24 hours.
  • New stories created when a user reshares a story will not be returned. Reshared stories include stories created using the Add Yours Templates.
  • New posts created when a user accepts collaboration requests will not be returned.
  • Use the dataType query parameter to request only posts or only stories.

​
Snapchat

  • Story and Saved Story items include a mediaUrls array with the downloadable media URL of each Snap in that Story. Spotlights are single-asset and do not include mediaUrls.
  • Fetching per-Snap media requires an additional request per Story, which adds latency. Set the media query parameter to false to skip it and return Story/Saved Story items without mediaUrls for faster, metadata-only responses. Example: GET https://api.ayrshare.com/api/history/snapchat?media=false.

​
Header Parameters

​
Path Parameters

​
string
required
The platform of the posts to retrieve. Values: bluesky, facebook, instagram, linkedin, pinterest, snapchat, threads, tiktok, twitter, youtube.

​
Query Parameters

​
number
default:10
Number of history records to return. Max limit: 500*High limits may result in slower response times, so we recommend using a limit of no more than 100.*Higher limits are available on Enterprise plans. Please contact your account manager for details.
​
boolean
default:false
Skip gathering full analytics for Facebook Pages and Instagram. Returns only the Social Post ID. Should be used if analytics aren’t needed (only need the Social Post ID), for a faster return, or errors occur when limit > 100.
​
boolean
default:10
Facebook only. By default the posts returned are from the Facebook Page feed. You may also choose to only return posts published by the page.Use feed (default) when you want a more comprehensive view of all content associated with the page, including interactions from other users. Use pagePublished when you only want to retrieve posts made by the page itself.
​
string
X/Twitter only. This parameter allows you to retrieve posts from a specific X/Twitter user by their numeric ID, rather than from your linked account.For example, to get all posts from the handle @Google, you would use their numeric userId 20536157.You can find any X/Twitter user’s numeric userId by using the Brands Get User endpoint.Note: Use only the API KEY in the header to make this request. Do not include the Profile Key.
​
string
X/Twitter only. This parameter allows you to retrieve posts from a specific X/Twitter user by their handle, rather than from your linked account.For example, to get all posts from the handle @Google.Note: Use only the API KEY in the header to make this request. Do not include the Profile Key.
​
string
Cursor-based pagination for retrieving the next page of results. Pass the next value from the previous response’s meta.pagination object to fetch the next set of posts.
​
string
Facebook only. ISO UTC date string to filter posts created on or after this date. Use with until for a specific date range.Example: since=2026-03-17
​
string
Facebook only. ISO UTC date string to filter posts created on or before this date. Use with since for a specific date range.Example: until=2026-03-20
​
string
Facebook and Instagram. Filter the type of content returned. By default, both regular posts and active Stories are returned.Values:
  • posts — regular posts only (no Stories)
  • stories — Stories only
Omit this parameter to return both posts and Stories (default behavior).Note: For Facebook, expired/archived Stories (older than 24 hours) are automatically filtered out. For Instagram, Stories are only available for 24 hours.
​
boolean
default:true
Snapchat only. When true (default), Story and Saved Story history items include a mediaUrls array with each Snap’s downloadable media URL. Fetching that media requires an extra request per Story, so set media=false to skip it for faster responses when you only need the Story metadata.

​
Pagination Response

When using cursor-based pagination (with next query parameter), the response includes a meta.pagination object containing pagination state. The posts array in each paginated response contains objects with the same structure as shown in the response examples below for each platform.
​
object
Pagination metadata for cursor-based navigation through results.

​
Partial Results

Retrieving history from some platforms takes several requests behind the scenes. If one of those requests fails part-way through, the posts already retrieved are still returned — but the list is incomplete, and the response says so with status: "partial" instead of "success".
​
string
"success" when the full requested history was retrieved, or "partial" when only some of it was. A "partial" response is not an error: the posts it contains are accurate, there are simply fewer of them than exist.
Treat "partial" as “this page is incomplete”, not as “this is everything”. Counting posts, or deriving totals from a "partial" response, will understate the real figures. Request again to get the full history — partial responses are never cached, so a retry always re-reads from the platform.
Partial response