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.
Get a history of posts sent via Ayrshare, in descending order (most recent to oldest). With this endpoint you can retrieve posts from a specific date range, status, social network, or the last n days. History status fields values:
  • awaiting approval: Posts are awaiting to be approved via the approval workflow.
  • deleted: Post has been deleted. Note: deleted posts are only returned with the status query filter. Please see below.
  • error: An error occurred with one or more social networks.
  • paused: A scheduled post that has been paused.
  • pending: The post has not yet been processed. Typically a scheduled post.
  • success: The post was successfully sent to all social networks.
Additional information:
  • The Ayrshare Post ID is returned in the response id field.
  • To retrieve posts that originated outside of Ayrshare, such as posts manually created directly at the social network, use the history platform endpoint.
  • If only an individual post is required, use the post history by id endpoint.
  • The history endpoint JSON results are cached for 1 minute if the limit is greater than the default value of 25.

​
Header Parameters

​
Query Parameters

​
number
default:25
Returns the last n number of posts. For example, if you only want the most recent post, set limit=1.Default: 25 posts. Max value: 1000.
​
array
Filter by social network platforms. Platform values: bluesky, facebook, gmb, instagram, linkedin, pinterest, reddit, snapchat, telegram, threads, tiktok, twitter, youtube. Note, uses OR logic: ["facebook", "instagram"] returns posts from either.
​
string
Return posts from and including this start date. Start date for the history in ISO 8601 format. For example, use format YYYY-MM-DDThh:mm:ssZ and send as 2026-07-08T12:30:00Z. Please see utctime for more examples.
​
string
Return posts up to and including this end date. End date for the history in ISO 8601 format. For example, use format YYYY-MM-DDThh:mm:ssZ and send as 2026-07-08T12:30:00Z. Please see utctime for more examples.
​
number
default:30
Returns the last n days of posts by the publish date, i.e. scheduleDate. Default 30 days.
  • The lastDays will be ignored if startDate and endDate are provided.
  • If the value is zero 0 will return the entire history of posts.
  • If the value is greater than 0, it will return the last n days of posts.
  • For example, lastDays=5 returns the last 5 days of posts and lastDays=0 returns all posts determined by the limit.
​
string
Filter by current status of post. Valid values: success, error, processing, pending, paused, deleted, and awaiting approval. Processing indicates the post is currently being sent. Pending indicates the post is scheduled to be posted at a future date.
Deleted posts are not returned by default. They are only returned with the status query filter set to status=deleted.
​
string
The type of post to retrieve, either post that were sent immediately or scheduled post using the scheduleDate field. Values: immediate or scheduled.
​
string
When creating an auto repost an ID is assigned to track that series of posts. Retrieve posts by auto repost ID or use the value of all to get all auto reposts.