Skip to main content
GET
/
history
curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100

{
  "history": [
    {
        "errors": [],
        "post": "This is the  post I sent",
        "platforms": [
            "twitter",
            "facebook"
        ],
        "postIds": [
            {
                "status": "success",
                "id": "1288968500063775749",    // Twitter Social Post ID
                "platform": "twitter"
            },
            {
                "id": "104923907983682_108683297607743", // Facebook Social Post ID
                "status": "success",
                "platform": "facebook"
            }
        ],
        "urls": [],
        "type": "now",
        "notes": "Approved by John Smith",  // Reference notes set via /post
        "created": "2022-05-20T17:25:06Z",
        "status": "deleted",
        "scheduleDate": {    // In a future release changed to "scheduleDate": "2020-11-05T12:21:29Z"
            "_seconds": 1604578889,
            "_nanoseconds": 211000000,
            "utc": "2020-11-05T12:21:29Z"
        },
        "id": "rhn6u7wwz2WxGv6MZGK9" // Ayrshare Top-Level Post ID
    },
    {
        "status": "success",
        "platforms": [
            "twitter",
            "facebook"
        ],
        "created": "2022-05-20T17:25:06Z",
        "post": "Sometimes we need to take a break for lunch.",
        "scheduleDate": {    // In a future release changed to "scheduleDate": "2020-11-05T12:21:29Z"
            "_seconds": 1604578889,
            "_nanoseconds": 211000000,
            "utc": "2020-11-05T12:21:29Z"
        },
        "type": "now",
        "postIds": [
            {
                "platform": "twitter",
                "id": "1288890036000983105", // Twitter Social Post ID
                "status": "success"
            },
            {
                "id": "104923907983682_108329970009742", // Facebook Social Post ID
                "status": "success",
                "platform": "facebook",
                "isVideo": true // Video post
            }
        ],
        "errors": [],
        "urls": [],
        "id": "wWIY0OEirdNeYSJYm1Xa" // Ayrshare Post ID
    },
    {   // Awaiting approval post - Approved by user
        "approved": true,
        "approvedBy": "9abf1426d6ce9122ef11c7222e1",
        "approvedDate": "2025-06-06T12:28:12Z",
        "created": "2025-06-06T12:27:56Z",
        "errors": [],
        "id": "sujQsrXtroJU0NEOlY38",
        "mediaUrls": [],
        "platforms": [
            "twitter"
        ],
        "post": "I failed my way to success. - Thomas Edison",
        "postIds": [
            {
                "status": "success",
                "id": "193096515330813",
                "postUrl": "https://twitter.com/RetiretyHQ/status/19309651533081",
                "platform": "twitter"
            }
        ],
        "profileTitle": "Primary Profile",
        "refId": "9abf1426d6ce9122ef11c7222e1",
        "requiresApproval": true,
        "scheduleDate": "2025-06-06T12:27:56Z",
        "shortenLinks": false,
        "status": "success",
        "type": "now"
    },
    {   // Awaiting approval post - Rejected by user
        "approved": false,
        "created": "2025-06-06T12:23:48Z",
        "id": "XL5xHeNK8HGTg07qxzmd",
        "mediaUrls": [],
        "platforms": [
            "twitter"
        ],
        "post": " Honesty is the first chapter in the book of wisdom. - Thomas Jefferson",
        "profileTitle": "Primary Profile",
        "refId": "9abf1426d6ce9122ef11c72bd62eddw2",
        "rejectedBy": "9abf1426d6ce9122ef11c7222e1",
        "rejectedDate": "2025-06-06T12:23:58Z",
        "requiresApproval": true,
        "scheduleDate": "2025-06-06T12:23:48Z",
        "shortenLinks": false,
        "status": "awaiting approval",
        "type": "now"
    }
        
   ],
    "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
    "count": 100,
    "lastUpdated": "2025-04-05T22:44:14.209Z",
    "nextUpdate": "2025-04-05T22:45:14.209Z"
}
Available on Basic, Premium, Business, Enterprise plans.
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

​
Authorization
string
required
API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY
​
Profile-Key
string
Profile Key of a User Profile.

Format: Profile-Key: PROFILE_KEY

​
Query Parameters

​
limit
number
default:25
Returns the last n number of posts. For example, if you only want the most recent post, set limit=1. If not present will return all records contained within lastDays.Default: 25 posts. Max value: 1000.
​
platforms
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.
​
startDate
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.
​
endDate
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.
​
lastDays
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.
​
status
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.
​
type
string
The type of post to retrieve, either post that were sent immediately or scheduled post using the scheduleDate field. Values: immediate or scheduled.
​
autoRepostId
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.
curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100

{
  "history": [
    {
        "errors": [],
        "post": "This is the  post I sent",
        "platforms": [
            "twitter",
            "facebook"
        ],
        "postIds": [
            {
                "status": "success",
                "id": "1288968500063775749",    // Twitter Social Post ID
                "platform": "twitter"
            },
            {
                "id": "104923907983682_108683297607743", // Facebook Social Post ID
                "status": "success",
                "platform": "facebook"
            }
        ],
        "urls": [],
        "type": "now",
        "notes": "Approved by John Smith",  // Reference notes set via /post
        "created": "2022-05-20T17:25:06Z",
        "status": "deleted",
        "scheduleDate": {    // In a future release changed to "scheduleDate": "2020-11-05T12:21:29Z"
            "_seconds": 1604578889,
            "_nanoseconds": 211000000,
            "utc": "2020-11-05T12:21:29Z"
        },
        "id": "rhn6u7wwz2WxGv6MZGK9" // Ayrshare Top-Level Post ID
    },
    {
        "status": "success",
        "platforms": [
            "twitter",
            "facebook"
        ],
        "created": "2022-05-20T17:25:06Z",
        "post": "Sometimes we need to take a break for lunch.",
        "scheduleDate": {    // In a future release changed to "scheduleDate": "2020-11-05T12:21:29Z"
            "_seconds": 1604578889,
            "_nanoseconds": 211000000,
            "utc": "2020-11-05T12:21:29Z"
        },
        "type": "now",
        "postIds": [
            {
                "platform": "twitter",
                "id": "1288890036000983105", // Twitter Social Post ID
                "status": "success"
            },
            {
                "id": "104923907983682_108329970009742", // Facebook Social Post ID
                "status": "success",
                "platform": "facebook",
                "isVideo": true // Video post
            }
        ],
        "errors": [],
        "urls": [],
        "id": "wWIY0OEirdNeYSJYm1Xa" // Ayrshare Post ID
    },
    {   // Awaiting approval post - Approved by user
        "approved": true,
        "approvedBy": "9abf1426d6ce9122ef11c7222e1",
        "approvedDate": "2025-06-06T12:28:12Z",
        "created": "2025-06-06T12:27:56Z",
        "errors": [],
        "id": "sujQsrXtroJU0NEOlY38",
        "mediaUrls": [],
        "platforms": [
            "twitter"
        ],
        "post": "I failed my way to success. - Thomas Edison",
        "postIds": [
            {
                "status": "success",
                "id": "193096515330813",
                "postUrl": "https://twitter.com/RetiretyHQ/status/19309651533081",
                "platform": "twitter"
            }
        ],
        "profileTitle": "Primary Profile",
        "refId": "9abf1426d6ce9122ef11c7222e1",
        "requiresApproval": true,
        "scheduleDate": "2025-06-06T12:27:56Z",
        "shortenLinks": false,
        "status": "success",
        "type": "now"
    },
    {   // Awaiting approval post - Rejected by user
        "approved": false,
        "created": "2025-06-06T12:23:48Z",
        "id": "XL5xHeNK8HGTg07qxzmd",
        "mediaUrls": [],
        "platforms": [
            "twitter"
        ],
        "post": " Honesty is the first chapter in the book of wisdom. - Thomas Jefferson",
        "profileTitle": "Primary Profile",
        "refId": "9abf1426d6ce9122ef11c72bd62eddw2",
        "rejectedBy": "9abf1426d6ce9122ef11c7222e1",
        "rejectedDate": "2025-06-06T12:23:58Z",
        "requiresApproval": true,
        "scheduleDate": "2025-06-06T12:23:48Z",
        "shortenLinks": false,
        "status": "awaiting approval",
        "type": "now"
    }
        
   ],
    "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
    "count": 100,
    "lastUpdated": "2025-04-05T22:44:14.209Z",
    "nextUpdate": "2025-04-05T22:45:14.209Z"
}