> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Posts History

> Retrieve posts sent through Ayrshare from newest to oldest, filtered by date range, status, social network, post type, auto repost ID, or the last n days.

> [!NOTE]
>
> **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](https://www.ayrshare.com/docs/dashboard/connect-social-accounts/x-twitter-byo-keys.md) 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:

<ul>
  <li>
    `awaiting approval`: Posts are awaiting to be approved via the [approval
    workflow](https://www.ayrshare.com/docs/apis/post/overview.md#approval-workflow).
  </li>

  <li>
    `deleted`: Post has been deleted. Note: deleted posts are only returned with the status query
    filter. Please see below.
  </li>

  <li>`error`: An error occurred with one or more social networks.</li>
  <li>`paused`: A scheduled post that has been paused.</li>
  <li>`pending`: The post has not yet been processed. Typically a scheduled post.</li>
  <li>`success`: The post was successfully sent to all social networks.</li>
</ul>

Additional information:

<ul>
  <li>
    The [Ayrshare Post ID](https://www.ayrshare.com/docs/apis/overview.md#ayrshare-post-id) is returned in the response `id` field.
  </li>

  <li>
    To retrieve posts that originated outside of Ayrshare, such as posts manually created directly
    at the social network, use the [history platform](https://www.ayrshare.com/docs/apis/history/history-platform.md) endpoint.
  </li>

  <li>
    If only an individual post is required, use the [post history by
    id](https://www.ayrshare.com/docs/apis/history/get-history-id.md) endpoint.
  </li>

  <li>
    The history endpoint JSON results are cached for 1 minute if the `limit` is greater than the
    default value of 25.
  </li>
</ul>

## Header Parameters

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) 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`.

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](https://www.utctime.net/) 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](https://www.utctime.net/) for more examples.

**lastDays** `number` (default: 30)

Returns the last n days of posts by the publish date, i.e. `scheduleDate`. Default 30 days.

<ul>
  <li>The `lastDays` will be ignored if `startDate` and `endDate` are provided.</li>
  <li>If the value is zero 0 will return the entire history of posts.</li>
  <li>If the value is greater than 0, it will return the last n days of posts.</li>

  <li>
    For example, `lastDays=5` returns the last 5 days of posts and `lastDays=0` returns all posts
    determined by the `limit`.
  </li>
</ul>

**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.

> [!NOTE]
>
> 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.

```bash cURL theme={"system"}
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
```

```javascript JavaScript theme={"system"}
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);
```

```python Python theme={"system"}
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 PHP theme={"system"}
<?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);

```

```csharp C# theme={"system"}
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}");
            }
        }
    }
}
}
```

```json 200: Success theme={"system"}
{
  "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"
}
```

```json 400: History not found theme={"system"}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.