Posts History

History of Ayrshare Posts

GET /history

cURL

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

const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

import requests

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

r = requests.get('https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100', headers=headers)

print(r.json())

<?php

$apiUrl = 'https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100';
$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);

using System;
using System.Net.Http;
using System.Threading.Tasks;

namespace HistoryGETRequest_csharp
{
class History
{
    static async Task Main(string[] args)
    {
        string API_KEY = "API_KEY";
        string url = "https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " + API_KEY);

            try
            {
                var response = await client.GetStringAsync(url);
                Console.WriteLine(response);
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}
}

200: Success

{
  "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"
}

{
  "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. .../ayrshare.com/rest-api/endpoints/history#list-history-of-sent-and-scheduled-posts"
}

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

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

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

const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

import requests

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

r = requests.get('https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100', headers=headers)

print(r.json())

<?php

$apiUrl = 'https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100';
$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);

using System;
using System.Net.Http;
using System.Threading.Tasks;

namespace HistoryGETRequest_csharp
{
class History
{
    static async Task Main(string[] args)
    {
        string API_KEY = "API_KEY";
        string url = "https://api.ayrshare.com/api/history?startDate=2025-01-01T12:30:00Z&endDate=2025-03-01T12:30:00&limit=100";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " + API_KEY);

            try
            {
                var response = await client.GetStringAsync(url);
                Console.WriteLine(response);
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}
}

200: Success

{
  "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"
}

{
  "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. .../ayrshare.com/rest-api/endpoints/history#list-history-of-sent-and-scheduled-posts"
}