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
    },
   ],
    "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.

​
platform
array

Filter by social network platforms.

Platform values: bluesky, facebook, gmb, instagram, linkedin, pinterest, reddit, telegram, 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.

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
    },
   ],
    "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
    "count": 100,
    "lastUpdated": "2025-04-05T22:44:14.209Z",
    "nextUpdate": "2025-04-05T22:45:14.209Z"
}