history

History API Endpoint: Get the history of a post or all posts.

---

GET History of Sent and Scheduled Posts

GET https://app.ayrshare.com/api/history

Get a history of all posts sent via Ayrshare, in descending order (most recent to oldest). Only the past 30 days of history is returned unless the lastDays parameter is set.

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.

⮕ pending: The posts has not yet been processed. Typically a scheduled post.

⮕ success: The post was successfully sent to all social networks.

Query Parameters

Name	Type	Description
status	string	Filter by current status of post. Valid values: "success", "error", "processing", "pending", "deleted", and "awaiting approval". Processing indicated the post is currently being sent. Pending indicates the post is scheduled to be posted at a future date.
lastDays	number	Returns the last X days of posts by scheduleDate. Default 30 days. If the value is zero 0 will return the entire history of posts. E.g. lastDays=5 returns the last 5 days of posts and lastDays=0 returns all posts determined by the lastRecords.
lastRecords	number	Returns the last X posts. For example, if you only want the most recent post, set lastRecords=1. If not present will return all records contained within lastDays (see above). Default 25 posts. Max value 500. Additional history available upon request.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200 Success

[
    {
        "errors": [],
        "post": "This is the  post I sent",
        "platforms": [
            "twitter",
            "facebook"
        ],
        "postIds": [
            {
                "status": "success",
                "id": "1288968500063775749",    // Twitter Social ID
                "platform": "twitter"
            },
            {
                "id": "104923907983682_108683297607743", // Facebook Social 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 ID
                "status": "success"
            },
            {
                "id": "104923907983682_108329970009742", // Facebook Social ID
                "status": "success",
                "platform": "facebook",
                "isVideo": true // Video post
            }
        ],
        "errors": [],
        "urls": [],
        "id": "wWIY0OEirdNeYSJYm1Xa" // Ayrshare Post ID
    },
]

400 History not found

{
    "action": "history",
    "status": "error",
    "code": 221,
    "message": "History not found for the past 30 days. Please see the docs on how to retrieve additional history. https://docs.ayrshare.com/rest-api/endpoints/history#list-history-of-sent-and-scheduled-posts"
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/history

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/history", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

headers = {'Authorization': 'Bearer API_KEY'}

r = requests.get('https://app.ayrshare.com/api/history', headers=headers)
    
print(r.json())

PHP

<?php

$apiUrl = 'https://app.ayrshare.com/api/history';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

C#

using System;
using System.Net;
using System.IO;

namespace HistoryGETRequest_charp
{
    class History
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/history";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

---

GET History by ID

GET https://app.ayrshare.com/api/history/:id

Get the history for a specific posts. Replace :id with the Ayrshare top level post ID.

Path Parameters

Name	Type	Description
id*	string	Ayrshare Post ID returned from /post

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200 Success

[
    {
        "tier": "business",
        "status": "success",
        "mediaUrls": [
            "https://images.ayrshare.com/imgs/GhostBusters.jpg"
        ],
        "postIds": [
            {
                "platform": "facebook",
                "postUrl": "https://www.facebook.com/1105775157895689_361710168628052",
                "status": "success",
                "id": "105775157895689_361710168628052" // Facebook Social ID
            }
        ],
        "id": "TBEEAqAMMJoweA8wKHUp", // Ayrshare Post ID
        "errors": [],
        "platforms": [
            "facebook"
        ],
        "scheduleDate": {   // In a future release changed to "scheduleDate": "2020-11-05T12:21:29Z"
            "_seconds": 1604578889,
            "_nanoseconds": 211000000,
            "utc": "2020-11-05T12:21:29Z"
        },
        "createDate": {    // deprecated, use created
            "_seconds": 1653067506,
            "_nanoseconds": 179000000,
            "utc": "2022-05-20T17:25:06Z"
        },
        "created": "2022-05-20T17:25:06Z",
        "shortenLinks": true,
        "post": "Today is a great day",
        "notes": "Approved by John Smith", // reference notes set via /post
        "type": "scheduled"
    }
]

400 Post not found

{
    "action": "history",
    "status": "error",
    "code": 221,
    "message": "History not found.",
    "id": "4W3f3RPr6QSrw8S5Yo8"
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

headers = {'Authorization': 'Bearer API_KEY'}

r = requests.get('https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl', headers=headers)
    
print(r.json())

PHP

<?php

$apiUrl = 'https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl'; // Replace with your post ID
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

C#

using System;
using System.Net;
using System.IO;

namespace HistoryGETRequest_charp
{
    class History
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

---

GET Posts for a Platform

GET https://app.ayrshare.com/api/history/:platform

Get Facebook, Instagram, LinkedIn, Pinterest, TikTok, Twitter, or YouTube posts and analytics, even post that did not originate via via Ayrshare.

The ID returned is the low-level post ID directly from the social network and not the Ayrshare Post ID. For example, you can retrieve a post that was manually shared on facebook.com and use the low-level Facebook ID to get comments or analytics.

If you do not need posts that originated outside of Ayrshare, simply use the top-level id returned in a post on comment, analytics, or history.

:platform = facebook, instagram, linkedin, pinterest, tiktok, twitter, youtube.

Example: https://app.ayrshare.com/api/history/instagram

⮕ LinkedIn only supports Company Page history. LinkedIn Personal Page history is not supported by LinkedIn.

Available for Business Plan users only.

Path Parameters

Name	Type	Description
platform*	string	The platform of the posts to retrieve. Values: facebook, instagram, linkedin, pinterest, tiktok, twitter, youtube

Query Parameters

Name	Type	Description
limit	number	Number of history records to return. Default 10, Max: 300.
skipAnalytics	boolean	Skip gathering full analytics for Facebook Pages and Instagram. Returns only the social ID. Should be used if analytics aren't needed, for a faster return, or errors occur when limit > 100. Default: false

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200 Successful retrieval of history

{
    "status": "success",
    "posts": [
        // Facebook Response Example
        // Note: If the FB page has fewer than 100 likes then not all analytics data available.
        {
            "clicksUnique": 31,
            "created": "2022-06-14T23:43:21Z",
            "commentsCount": 13,
            "engagedUsers": 3,
            "fullPicture": "https://scontent.ford4-1.fna.fbcdn.net/v/t39.30808-6/287997502_758105082307121_n.jpg?stp=dst-jpg_s720x720&_nc_cat=101&ccb=1-7&_nc_sid=8024bb&_nc_ohc=EkktQTp_uWIAX_xtTxV&_nc_ht=scontent.ford4-1.fna&edm=AKK4YLsEAAAA&oh=00_AT-Y5Ht2Pl3MeY-qIBs6BC10SbZ-47Vfcc7DKiQrCnIUA&oe=62AEEECA",
            "id": "104619420979033_758005082307127", // Facebook Social ID
            "impressionsUnique": 0,
            "isPopular": false,
            "lastUpdated": "2022-06-14T23:43:38.359Z",
            "likeCount": 38,
            "mediaUrls": [    // If attached photos or video
                {
                    "media": {
                        "image": {
                            "height": 412,
                            "src": "https://scontent-lga3-1.xx.fbcdn.net/v/t15.5256-10/294978304_1014487762575117_6279324362130508123_n.jpg?stp=dst-jpg_s720x720&_nc_cat=101&ccb=1-7&_nc_sid=ad6a45&_nc_ohc=y3bYN-PGN0YAX9kO2qn&_nc_ht=scontent-lga3-1.xx&edm=AKK4YLsEAAAA&oh=00_AT9by7D4y4sjY4BW5RW53JO6BaG2UkpUCCJrrugW7GDW9w&oe=62E23000",
                            "width": 720
                        },
                        // Source if mediaType is video
                        "source": "https://video-lga3-1.xx.fbcdn.net/v/t39.25447-2/294718581_137662848672158_7246454806912028286_n.mp4?_nc_cat=111&vs=696d8a2ba08f208b&_nc_vs=HBkcFQAYJEdIVU1rUkdlb1RFaE5IMEFBSDdPNmVaQWxKQmtibWRqQUFBRhUAAsgBAEsGiBJwcm9ncmVzc2l2ZV9yZWNpcGUBMQ1zdWJzYW1wbGVfZnBzABB2bWFmX2VuYWJsZV9uc3ViACBtZWFzdXJlX29yaWdpbmFsX3Jlc29sdXRpb25fc3NpbQAoY29tcHV0ZV9zc2ltX29ubHlfYXRfb3JpZ2luYWxfcmVzb2x1dGlvbgARZGlzYWJsZV9wb3N0X3B2cXMAFQAlABwAACac%2FNfk2tKqARWQTigCQzMYC3Z0c19wcmV2aWV3HBdAGZmZmZmZmhhEZGFzaF9pNGxpdGViYXNpY19wYXNzdGhyb3VnaGFsaWduZWRfNDgwX2NyZl8yOF9tYWluXzMuMF9mcmFnXzJfdmlkZW8SABgYdmlkZW9zLnZ0cy5jYWxsYmFjay5wcm9kOBJWSURFT19WSUVXX1JFUVVFU1QbD4gVb2VtX3RhcmdldF9lbmNvZGVfdGFnBm9lcF9zZBNvZW1fcmVxdWVzdF90aW1lX21zATAMb2VtX2NmZ19ydWxlCnNkX3VubXV0ZWQTb2VtX3JvaV9yZWFjaF9jb3VudAI5OBFvZW1faXNfZXhwZXJpbWVudAAMb2VtX3JvaV9ub3RlC3Byb2dyZXNzaXZlEW9lbV9yb2lfdXNlcl90aWVyAB5vZW1fcm9pX3ByZWRpY3RlZF93YXRjaF90aW1lX3MBMBZvZW1fcm9pX3JlY2lwZV9iZW5lZml0BTAuMDAwJW9lbV9yb2lfc3RhdGljX2JlbmVmaXRfY29zdF9ldmFsdWF0b3ILcHJvZ3Jlc3NpdmUMb2VtX3ZpZGVvX2lkEDEyNjk2MTcwNzM3NzgxNTESb2VtX3ZpZGVvX2Fzc2V0X2lkDzc5ODQ2NjE3NDg0NzE4OBVvZW1fdmlkZW9fcmVzb3VyY2VfaWQPMzc1MjU0ODg3ODkwNzAyHG9lbV9zb3VyY2VfdmlkZW9fZW5jb2RpbmdfaWQPNDUwODU0MzgzNjE1MDc5DnZ0c19yZXF1ZXN0X2lkD2EyYThlNWU4OTBkNTRmMyUCHBwcFfDmFxsBVQACGwFVAAIcFQIAAAAWgLq3AwAlxAEbB4gBcwQ1ODkyAmNkCjIwMjItMDctMjQDcmNiATADYXBwBVdhdGNoAmN0GERJUkVDVEVEX1BPU1RfQVRUQUNITUVOVBNvcmlnaW5hbF9kdXJhdGlvbl9zBTYuNDE3AnRzFHByb2dyZXNzaXZlX29yZGVyaW5nAA%3D%3D&ccb=1-7&_nc_sid=a06cc9&_nc_ohc=bA3WO4Dk72QAX9TB9ag&_nc_ht=video-lga3-1.xx&edm=AKK4YLsEAAAA&oh=00_AT_CzNhlIwNxY_7UMWIGQMNOtD-Aw_LGcVHnDWvcQJVkAw&oe=62E2ADE1&_nc_rid=780575090331889"
                    },
                    "mediaType": "video", // "link" or "photo"
                    "url": "https://www.facebook.com/115237020273490/videos/1269617073778151",
                    "videoId": "1269617073778151"
                }
            ],
            "negativeFeedback": 0,
            "negativeFeedbackUnique": 0,
            "nextUpdate": "2022-06-15T00:18:38.359Z",
            "parentId": "5764771300200609_742258953848744", // If a shared post, then the ID of the original post
            "post": "What a nice one",
            "postUrl": "https://www.facebook.com/104619420979033_758105082307121",
            "properties": [    // for videos only
                {
                    "name": "Length",
                    "text": "00:07"
                }
            ],
            "reactions": {         // Total lifetime
                "like": 1,         // Like reactions - The "like" reaction counts include both "like" and "care" reactions.
                "love": 1,         // Love reactions
                "anger": 1,        // Anger reactions
                "haha": 1,         // Haha reactions
                "wow": 1,          // Wow reactions
                "sorry": 1,        // Sorry reactions
                "total": 6         // Total number of reactions
            },
            "reactionsByType": 1,
            "statusType": "added_video", // Status actions: added_photos, added_video, app_created_story, approved_friend, created_event, created_group, created_note, mobile_status_update, published_story, shared_story, tagged_in_photo, wall_post
            "videoViewTime": 0,
            "videoViews": 0,
            "videoViewsUnique": 0
        },
        {
            "clicksUnique": 45,
            "created": "2022-06-14T14:53:01Z",
            "engagedUsers": 2,
            "fullPicture": "https://external.ford4-1.fna.fbcdn.net/emg1/v/t13/614683800928174083?url=https%3a%2f%2fwww.alphast.com%2fwp-content%2fuploads%2f2022%2f06%2fheadphones-scaled.jpg&fb_obo=1&utld=fbcdn.net&stp=dst-emg0_q75&ccb=13-1&oh=00_AT-MVM6lP-eWgsqCW6IhImKAJaGy71JIGIntjlVnZkJw&oe=62AAAC5C&_nc_sid=5f3a21",
            "id": "104619420979033_757752962332339", // Facebook Social ID
            "impressionsUnique": 1,
            "isPopular": false,
            "lastUpdated": "2022-06-14T23:40:48.453Z",
            "mediaUrls": [
                {
                    "mediaUrl": "link",
                    "url": "https://www.alphasht.com/finding-the-best-headphones/"
                }
            ],
 
            "negativeFeedback": 0,
            "negativeFeedbackUnique": 0,
            "nextUpdate": "2022-06-15T00:15:48.453Z",
            "post": "Finding The Best Headphones: Finding the best headphones for you depends on several factors.",
            "postUrl": "https://www.facebook.com/104619420979033_75775296233233",
            "reactions": {         // Total lifetime
                "like": 1,         // Like reactions - The "like" reaction counts include both "like" and "care" reactions.
                "love": 1,         // Love reactions
                "anger": 1,        // Anger reactions
                "haha": 1,         // Haha reactions
                "wow": 1,          // Wow reactions
                "sorry": 1,        // Sorry reactions
                "total": 6         // Total number of reactions
            },
            "reactionsByType": 1,
            "videoViewTime": 0,
            "videoViews": 0,
            "videoViewsUnique": 0
        },
        {    // Facebook Story
            "clicksUnique": 0,
            "commentsCount": 0,
            "created": "2024-03-15T19:36:29.000Z",
            "engagedUsers": 0,
            "id": "1593984754722429",
            "impressionsFanPaidUnique": 0,
            "impressionsFanUnique": 0,
            "impressionsOrganicUnique": 0,
            "impressionsPaidUnique": 0,
            "impressionsUnique": 0,
            "likeCount": 0,
            "mediaId": "1593984754722429",
            "mediaType": "video",
            "negativeFeedback": 0,
            "negativeFeedbackUnique": 0,
            "post": "",
            "postId": "1433249613981178",
            "postUrl": "https://facebook.com/stories/114251701259415/UzpfSVNDOjE0MzMyNDk2MTczMTQ1MTE=/?view_single=1",
            "reactions": {},
            "reactionsByType": 0,
            "sharesCount": 0,
            "statusType": "published",
            "videoViewTime": 0,
            "videoViews": 0,
            "videoViewsUnique": 0
        }
        ...
    // Instagram Response Example
        {
            "mediaUrl": "https://scontent.cdninstagram.com/v/t51.2885-15/75317300_249468363049056_6683482523516619964_n.jpg?",
            "permalink": "https://www.instagram.com/p/B5OBT3ygpfg/",
            "commentsCount": 0,
            "created": "2022-05-20T17:26:03Z",
            "likeCount": 0,
            "mediaProductType": "FEED", // Media product type: AD, FEED, STORY or REELS
            "mediaType": "IMAGE",       // Media type: CAROUSEL_ALBUM, IMAGE, or VIDEO
            "username": "thegoodone",
            "id": "17833140557332933", // Instagram Social ID
            "thumbnailUrl": "https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/277243581_1136333620462129_9111753545576538669_n.jpg",
            "post": "The #Mandalorian is on tonight instead of Friday",
            "postUrl": "https://www.instagram.com/p/B5OBT3ygpfg/"    // same as permalink
        },
        {
            "mediaUrl": "https://scontent.cdninstagram.com/v/t51.2885-15/72719989_401282024671549_6704610247561386099_n.jpg?",
            "permalink": "https://www.instagram.com/p/B6_EubJFlMI/",
            "commentsCount": 0,
            "created": "2022-05-20T17:26:03Z",
            "likeCount": 0,
            "mediaProductType": "REELS", // Media product type: AD, FEED, STORY or REELS
            "mediaType": "VIDEO",        // Media type: CAROUSEL_ALBUM, IMAGE, or VIDEO
            "username": "thegoodone",
            "id": "17933140557332933", // Instagram Social ID
            "thumbnailUrl": "https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/277243581_1136333620462129_9111753545576538669_n.jpg",
            "post": "And finally, number eleven of the best shows of 2019 is #Mandalorian #BabyYoda #Bestof2019", 
            "postUrl": "https://www.instagram.com/p/B6_EubJFlMI/"    // same as permalink
        },
        ...
        ...
        // LinkedIn Response Example
        {
            "clickCount": 0,
            "commentCount": 1,
            "created": "2022-12-28T16:07:38Z",
            "engagement": 0.6666666666666666,
            "id": "urn:li:share:701389826709", // LinkedIn Social ID
            "impressionCount": 3,
            "lastModified": "2022-12-28T16:07:38Z",
            "likeCount": 1,
            "post": "left thirty pocket track flower whistle",
            "postUrl": "https://www.linkedin.com/feed/update/urn:li:share:701389826709",
            "publishedAt": "2022-12-28T16:07:38Z",
            "reactions": {          // Get reactions on a LinkedIn share
                "like": 1,        // "Like in the UI      
                "praise": 2,      // "Celebrate" in the UI
                "maybe": 3,       // "Curious" in the UI
                "empathy": 3,     // "Love" in the UI
                "interest": 2     // "Insightful" in the UI
                "appreciation": 5 // "Support" in the UI
            },
            "shareCount": 0,
            "status": "PUBLISHED",
            "uniqueImpressionsCount": 3,
            "visibility": "PUBLIC"
        },
        {
            "clickCount": 0,
            "commentCount": 1,
            "created": "2022-12-28T17:05:11Z",
            "engagement": 0.16666666666666666,
            "id": "urn:li:share:70139127498", // LinkedIn Social ID
            "impressionCount": 12,
            "lastModified": "2022-12-28T17:05:11Z",
            "likeCount": 1,
            "mediaUrls": [ // please see https://docs.ayrshare.com/additional-info/upcoming-api-changes#changes-in-effect-december-1-2023
                {
                    "id": "urn:li:video:C4E10AQHz0RMm5aAiAg",
                    "url": "https://media.licdn.com/dms/image/C4E10AQHz0RMm5aAiAg"
                },
                {
                    "id": "urn:li:video:C4E10AQHz0RMm5adsH2",
                    "url": "https://media.licdn.com/dms/image/C4E10AQHz0RMm5adsH2"
                }
            ],
            "post": "no monkey gulf organization mood choose earn",
            "postUrl": "https://www.linkedin.com/feed/update/urn:li:share:70139127498",
            "publishedAt": "2022-12-28T17:05:11Z",
            "reactions": {          // Get reactions on a LinkedIn share
                "like": 1,        // "Like in the UI      
                "praise": 2,      // "Celebrate" in the UI
                "maybe": 3,       // "Curious" in the UI
                "empathy": 3,     // "Love" in the UI
                "interest": 2     // "Insightful" in the UI
                "appreciation": 5 // "Support" in the UI
            },
            "shareCount": 0,
            "status": "PUBLISHED",
            "uniqueImpressionsCount": 9,
            "visibility": "PUBLIC"
        }
        ...
        // Pinterest Response Example
        {
            "altText": "",
            "boardId": "955255839651522358",
            "coverImageUrl": "https://i.pinimg.com/originals/7e/ea/af/7eeaaf4bce167902b06fe3370227e.jpg",
            "created": "2022-08-09T22:25:12Z",
            "dominantColor": "#353027",    // Dominant pin color. Hex number, e.g. "#6E7874"
            "duration": 6416,              // Time in millisecord
            "height": 1062,
            "id": "7184649418547260", // Pinterest Social ID
            "link": "",
            "mediaType": "video",
            "mediaUrl": "https://i.pinimg.com/originals/7e/ea/af/7eeaaf4bce167902b06fe3370227e.jpg",
            "note": "What a great post",
            "post": "You are what you believe yourself to be. - Paulo Coelho",
            "postUrl": "https://www.pinterest.com/pin/7184649418547260",
            "productTags": [],
            "title": "My new post",
            "username": "ayrshare",
            "width": 1856
        },
        {
            "altText": "",
            "created": "2022-08-09T22:25:12Z",
            "dominantColor": "#7c7c7c",
            "height": 600,
            "id": "7184649468512979", // Pinterest Social ID
            "link": "",
            "mediaType": "image",
            "mediaUrl": "https://i.pinimg.com/originals/1b/0a/02/1b0a02123fba55042474b61bb2aa1.jpg",
            "post": "Peace begins with a smile. - Mother Teresa",
            "postUrl": "https://www.pinterest.com/pin/7184649468512979",
            "username": "ayrshare",
            "width": 600
        },
        {
            "altText": "",
            "created": "2022-10-17T12:26:05Z",
            "dominantColor": "#7f805e",
            "id": "36493237618990511", // Pinterest Social ID
            "link": "",
            "mediaType": "multiple_mixed",
            "mediaUrls": [
                {
                    "mediaType": "image",
                    "height": 442,
                    "width": 249,
                    "mediaUrl": "https://i.pinimg.com/originals/6c/e2/1f/6ce21fa3936b51cd39c34be6f60dd469.jpg"
                },
                {
                    "mediaType": "image",
                    "height": 589,
                    "width": 332,
                    "mediaUrl": "https://i.pinimg.com/originals/9370f0845be155b5640c0f.jpg"
                },
                {
                    "mediaType": "image",
                    "height": 589,
                    "width": 332,
                    "mediaUrl": "https://i.pinimg.com/originals/9370f0845be155b5640c0f.jpg"
                },
                {
                    "mediaType": "image",
                    "height": 589,
                    "width": 332,
                    "mediaUrl": "https://i.pinimg.com/originals/9370f0845be155b5640c0f.jpg"
                },
                {
                    "mediaType": "video",
                    "duration": 19600,
                    "height": 1280,
                    "width": 720,
                    "mediaUrl": "https://i.pinimg.com/videos/thumbnails/originals/9370f0845be155b5640c0f.jpg"
                }
            ],
            "post": " ",
            "postUrl": "https://www.pinterest.com/pin/36493237618990511",
            "username": "johnsmith"
        },
        ...
        // TikTok Response Example
        {
            "audienceCountries": [
                {
                    "country": "CO",
                    "percentage": 0.0015
                },
                {
                    "country": "ES",
                    "percentage": 0.0029
                },
                {
                    "country": "GB",
                    "percentage": 0.0029
                },
                {
                    "country": "US",
                    "percentage": 0.9604
                },
                {
                    "country": "SA",
                    "percentage": 0.0015
                },
                {
                    "country": "CA",
                    "percentage": 0.0015
                },
                {
                    "country": "GE",
                    "percentage": 0.0015
                },
                {
                    "country": "IT",
                    "percentage": 0.0015
                },
                {
                    "country": "PR",
                    "percentage": 0.0029
                },
                {
                    "country": "RU",
                    "percentage": 0.022
                }
            ],
            "averageTimeWatched": 2.0132,
            "commentsCount": 1,
            "created": "2024-02-26T18:32:00Z",
            "embedUrl": "https://www.tiktok.com/static/profile-video?id=73399801580586794&",
            "fullVideoWatchedRate": 0.0176,
             "id": "7339980158058679594",
            "impressionSources": [
                {
                    "impression_source": "Search",
                    "percentage": 0
                },
                {
                    "impression_source": "Sound",
                    "percentage": 0
                },
                {
                    "impression_source": "other_profile_vv",
                    "percentage": 0
                },
                {
                    "impression_source": "Follow",
                    "percentage": 0
                },
                {
                    "impression_source": "For You",
                    "percentage": 1
                },
                {
                    "impression_source": "Hashtag",
                    "percentage": 0
                },
                {
                    "impression_source": "Personal Profile",
                    "percentage": 0
                }
            ],
            "likeCount": 2,
            "mediaType": "video",
            "musicTitle": "♬ original sound - Mack",
            "musicUrl": "https://www.tiktok.com/music/original-sound",
            "name": "Mack",
            "post": "I’ve failed over and over and over again in my life and that is why I succeed. - Michael Jordan",
            "postUrl": "https://www.tiktok.com/@happy/video/7339980158058679594",
            "reach": 653,
            "shareUrl": "https://www.tiktok.com/@happy/video/7339980158058679594",
            "shareCount": 2,
            "tags": [],
            "thumbnailHeight": 1024,
            "thumbnailUrl": "https://p19-sign.tiktokcdn-us.com/obj/tos-useast5-p-85c255-tx/oIpT 9CLHAaQfuD67E3jfAFJ5eVDuF5Ibkmszg?x-expires=1709305200&x-signature=ZBTR0Q%2B4KLi8szRCir8eYEcAs1s%3D",
            "thumbnailWidth": 576,
            "totalTimeWatched": 1373,
            "url": "https://www.tiktok.com/@happy",
            "videoDuration": 11.332,
            "videoViews": 697
        },
        ...
        // Twitter Response Example
        // Note: Non-public and organic metrics only available last 30-days of Tweets
        {
            "created": "2022-05-20T20:07:53.000Z",
            "id": "1187026023991603", // Twitter Social ID
            "media": [                                  // Attached media
                {
                    "mediaKey": "7_1555577959943217152",
                    "previewImageUrl": "https://pbs.twimg.com/ext_tw_video_thumb/1555577959943217152/pu/img/f4M9veIozFjQA_XD.jpg",
                    "durationMs": 2168,    // Duration in milliseconds, videos only
                    "type": "video"        // or "photo", "animated_gif"
                }
            ],
            "nonPublicMetrics": {         // Use this to determine the total number of impressions generated for the Tweet. Only available for Tweets created the last 30 days.
                "impressionCount": 1,     // Number of times the Tweet has been viewed
                "userProfileClicks": 0
            },    
            "organicMetrics": {          // Use this to measure organic engagement for the Tweet. Only available for Tweets created the last 30 days.
                "userProfileClicks": 2,
                "impressionCount": 4,    // Number of times the Tweet has been viewed organically.
                "replyCount": 3,
                "retweetCount": 1,
                "likeCount": 234
            },
            "possiblySensitive": false,  // Tweet contains possibly sensitive information
            "post": "To effectively communicate, we must realize that we are all different",
            "postUrl": "https://twitter.com/myhandle/status/1187026023991603",
            "publicMetrics": {            // Use this to measure Tweet engagement. Only available for Tweets created the last 30 days.
                "retweetCount": 2,
                "replyCount": 2,
                "likeCount": 5,
                "quoteCount": 1
            },
            "referencedTweets": [        // If a quoted or reply tweet
                {
                    "type": "quoted",    // or "replied_to"
                    "id": "1556718165828276224",    // Quoted or replied Tweet ID
                    "url": "https://www.twitter.com/1556718165828276224" // Quoted or Replied Tweet URL
                }
            ],
            "source": "Ayrshare",        // Determine if a Twitter user posted from the web, mobile device, or other app.
            "text": "To effectively communicate, we must realize that we are all different" // Deprecated, use "post" field
        },
        {
            "authorId": "1194338779881472",
            "created": "2023-12-27T03:24:23.000Z",
            "createdAt": "2023-12-27T03:24:23.000Z",
            "editHistoryTweetIds": [
                "17398682514485715"
            ],
            "id": "17398682514485715",
            "media": [ // available for videos and gifs
                {
                    "nonPublicMetrics": {
                        "playback100Count": 2,
                        "playback0Count": 55,
                        "playback50Count": 4,
                        "playback25Count": 11,
                        "playback75Count": 2
                    },
                    "publicMetrics": {
                        "viewCount": 27
                    },
                    "durationMs": 28240,
                    "organicMetrics": {
                        "playback100Count": 2,
                        "playback0Count": 55,
                        "playback25Count": 11,
                        "playback75Count": 2,
                        "playback50Count": 4,
                        "viewCount": 27
                    },
                    "mediaKey": "7_1739849636389814272",
                    "previewImageUrl": "https://pbs.twimg.com/ext_tw_video_thumb/1739849636389814272/pu/img/bCkAdkD0R00-ZlkY.jpg",
                    "width": 1920,
                    "type": "video",
                    "height": 1080,
                    "mediaUrls": [
                        {
                            "bitRate": 256000,
                            "contentType": "video/mp4",
                            "mediaUrl": "https://video.twimg.com/ext_tw_video/1739849636389814272/pu/vid/avc1/480x270/4RoZCqynednVMFgy.mp4?tag=12"
                        },
                        {
                            "bitRate": 832000,
                            "contentType": "video/mp4",
                            "mediaUrl": "https://video.twimg.com/ext_tw_video/1739849636389814272/pu/vid/avc1/640x360/RYy5iHTIxu7_iyZm.mp4?tag=12"
                        },
                        {
                            "bitRate": 2176000,
                            "contentType": "video/mp4",
                            "mediaUrl": "https://video.twimg.com/ext_tw_video/1739849636389814272/pu/vid/avc1/1280x720/9UpR90ekFA-9Ucxo.mp4?tag=12"
                        },
                        {
                            "contentType": "application/x-mpegURL",
                            "mediaUrl": "https://video.twimg.com/ext_tw_video/1739849636389814272/pu/pl/0AVy2xIOLQcsrEZG.m3u8?tag=12&container=fmp4"
                        }
                    ]
                }
            ],
            "nonPublicMetrics": {
                "impressionCount": 54,
                "userProfileClicks": 0
            },
            "organicMetrics": {
                "userProfileClicks": 0,
                "likeCount": 0,
                "replyCount": 0,
                "impressionCount": 54,
                "retweetCount": 0
            },
            "possiblySensitive": false,
            "post": "Family is the most important thing in the world. - Diana, Princess of Wales https://t.co/MgYxnJDer6",
            "postUrl": "https://twitter.com/superme/status/17398682514485715",
            "publicMetrics": {
                "retweetCount": 0,
                "replyCount": 0,
                "likeCount": 0,
                "quoteCount": 0,
                "bookmarkCount": 0,
                "impressionCount": 54
            }
        },
        ...
        // YouTube Response Example
        {
            "created": "2022-08-15T19:14:44Z",
            "description": "Doubt is not a pleasant condition, but certainty is absurd. - Voltaire", // Deprecated, use "post" field
            "id": "Q-4OuHCALVa", // YouTube Social ID
            "position": 0,
            "post": "Doubt is not a pleasant condition, but certainty is absurd. - Voltaire",
            "postUrl": "https://www.youtube.com/watch?v=Q-4OuHCALVa",
            "privacyStatus": "public",
            "thumbnailUrl": "https://i.ytimg.com/vi/Q-4OuHCALVa/default.jpg",
            "title": "Yo time"
        },
        {
            "created": "2022-08-08T22:24:42Z",
            "description": "Little author little, one travels far. - J.R.R. Tolkien",  // Deprecated, use "post" field
            "id": "Btg4ysKnHea", // YouTube Social ID
            "position": 1,
            "post": "Little author little, one travels far. - J.R.R. Tolkien",
            "postUrl": "https://www.youtube.com/watch?v=Btg4ysKnHea",
            "privacyStatus": "unlisted",
            "thumbnailUrl": "https://i.ytimg.com/vi/Btg4ysKnHea/default.jpg",
            "title": "Nice one 2"
        },
    ],
    "lastUpdated": "2022-11-14T16:04:51.994Z",
    "nextUpdate": "2022-11-14T16:37:21.994Z"
}

400 Error Returning history

{
    "status": "error",
    "code": 196,
    "message": "Instagram is not connected"
}

400: Bad Request Getting History

{
    // When some of the data is not available from the social networks.
    // All available data is still returned
    "status": "error",
    "posts": [
        {... valid data },
        {
            "action": "analytics",
            "code": 187,
            "commentsCount": 0,
            "created": "2019-03-22T13:31:02Z",
            "createdTime": "2019-03-22T13:31:02+0000",
            "from": {
                "name": "Ayrshare",
                "id": "746346376697"
            },
            "fullPicture": "https://external.fphl1-1.fna.fbcdn.net/emg1/v/t13/",
            "id": "746346376697_3993223", // Facebook Social ID
            "isPopular": false,
            "likeCount": 2,
            "mediaUrls": [
                {
                    "description": "Dirk Cotton's approach to retirement planning.",
                    "media": {
                        "image": {
                            "height": 720,
                            "src": "https://external.fphl1-1.fna.fbcdn.net/emg1/v/t13/608115669879219",
                            "width": 720
                        }
                    },
                    "mediaType": "link",
                    "title": "The Retirement Planning Regime",
                    "url": "https://bit.ly/2RwaH"
                }
            ],
            "message": "Error getting analytics.",
            "post": "Error getting analytics.",
            "status": "error",
            "statusType": "shared_story"
        },
        {... valid data }
    ]
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-X GET https://app.ayrshare.com/api/history/instagram

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/history/instagram", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

headers = {'Authorization': 'Bearer API_KEY'}

r = requests.get('https://app.ayrshare.com/api/history/instagram', headers=headers)
    
print(r.json())

PHP

<?php

$apiUrl = 'https://app.ayrshare.com/api/history/instagram';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

C#

using System;
using System.Net;
using System.IO;

namespace HistoryGETRequest_charp
{
    class History
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/history/TBEAAqAMMJoweA9wKHUl";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

User Profile History

Get history data for a particular user profile by adding the PROFILE_KEY in the header.

History by Social ID

Retrieve history for posts that did not originate via Ayrshare by providing the low-level Social post ID. This Social ID is returned in the postIds field of the post endpoint or the id field from the get all history endpoint or the ID from a post URL, such as from this Facebook post.

The linked account must the owner of the post to retrieve the history.

Support platforms: Facebook, Instagram, Twitter, and YouTube with the following platform values: facebook, instagram, linkedin, twitter, youtube.

GET History by Social Id

GET https://app.ayrshare.com/api/history/:socialId

Retrieve history for a post that did not originate via Ayrshare.

Available for Business Plan users only.

Path Parameters

Name	Type	Description
socialId*	string	The social ID of the post.

Query Parameters

Name	Type	Description
searchPlatformId*	boolean	Always equals true
platform*	string	Values: facebook, instagram, linkedin, twitter, youtube

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Profile-Key	string	Profile Key of a user profile.

200: OK Successful Return

[
    {
        "commentsCount": 0,
        "created": "2024-01-25T23:01:23Z",
        "from": {
            "name": "Ayrshare",
            "id": "18930271191"
        },
        "id": "18930271191_39392923",
        "mediaUrls": [
            {
                "media": {
                    "image": {
                        "height": 720,
                        "src": "https://scontent-lga3-2.xx.fbcdn.net/v/...",
                        "width": 405
                    },
                    "source": "https://video-lga3-2.xx.fbcdn.net/o1/..."
                },
                "title": "🔥 Sneaker time!"
            }
        ],
        "messageTags": [
            {
                "id": "434786466522",
                "name": "#sneakerswap365",
                "offset": 242,
                "length": 15
            }
        ],
        "post": "🔥 Sneaker Time for all!",
        "postUrl": "https://www.facebook.com/reel/72681340799/",
        "lastUpdated": "2024-01-25T23:29:58.014Z",
        "nextUpdate": "2024-01-25T23:40:58.014Z"
    }

400: Bad Request Post Not Found

{
    "action": "get",
    "status": "error",
    "code": 221,
    "message": "The ID was not found. Please verify the id, API or Profile Keys, and required parameters.",
    "id": "7268134079",
    "lastUpdated": "2024-01-25T23:45:14.311Z",
    "nextUpdate": "2024-01-25T23:56:14.311Z"
}

Request Example

GET https://app.ayrshare.com/api/history/104923907983682_108329000309742?searchPlatformId=true&platform=facebook

Please see the /post endpoint Response 200 for another example of the Facebook Social ID 104923907983682_108329000309742