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

# 帖子历史

> Ayrshare 帖子的历史记录

export const XByoNotice = () => <Info>
  <strong>Targeting X/Twitter?</strong> Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
  <br /><br />
  <code>X-Twitter-OAuth1-Api-Key</code> — Your API Key (Consumer Key)<br />
  <code>X-Twitter-OAuth1-Api-Secret</code> — Your API Key Secret (Consumer Secret)
  <br /><br />
  <strong>One-time setup per Ayrshare account.</strong> You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do <em>not</em> create a new app per customer.
  <br /><br />
  Not linked yet? See the <a href="/dashboard/connect-social-accounts/x-twitter-byo-keys">full setup guide</a> to connect your X account.
  <br /><br />
  Your keys are never logged or stored by Ayrshare.
</Info>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

<XByoNotice />

获取通过 Ayrshare 发送的帖子历史，按降序（从最新到最早）排列。

通过此接口，你可以按特定日期范围、状态、社交网络或最近 n 天检索帖子。

历史记录 `status` 字段的取值：

<ul class="custom-bullets">
  <li>
    `awaiting approval`：帖子等待通过[审批流程](/apis/post/overview#approval-workflow)审核。
  </li>

  <li>
    `deleted`：帖子已删除。注意：删除的帖子只有在使用 status 查询过滤条件时才会返回。请见下文。
  </li>

  <li>`error`：一个或多个社交网络发生错误。</li>
  <li>`paused`：定时帖子已被暂停。</li>
  <li>`pending`：帖子尚未处理。通常为定时帖子。</li>
  <li>`success`：帖子已成功发送到所有社交网络。</li>
</ul>

其他信息：

<ul class="custom-bullets">
  <li>
    [Ayrshare Post ID](/apis/overview#ayrshare-post-id) 在响应的 `id` 字段中返回。
  </li>

  <li>
    如需检索来自 Ayrshare 之外的帖子（例如直接在社交网络上手动创建的帖子），
    请使用 [history platform](/apis/history/history-platform) 接口。
  </li>

  <li>
    如果只需要单个帖子的历史，请使用[按 id 查询帖子历史](/apis/history/get-history-id)接口。
  </li>

  <li>
    当 `limit` 大于默认值 25 时，history 接口的 JSON 结果会缓存 1 分钟。
  </li>
</ul>

## 请求头参数

<HeaderAPI />

## 查询参数

<ParamField query="limit" type="number" default={25}>
  返回最近的 <em>n</em> 条帖子。例如，如果只想获取最新一条帖子，设置 `limit=1`。
  如果不传，则返回 `lastDays` 范围内的所有记录。

  默认：`25` 条。最大值：`1000`。
</ParamField>

<ParamField query="platforms" type="array">
  按社交网络平台筛选。平台取值：`bluesky`、`facebook`、`gmb`、`instagram`、
  `linkedin`、`pinterest`、`reddit`、`snapchat`、`telegram`、`threads`、`tiktok`、`twitter`、
  `youtube`。注意：使用 `OR` 逻辑，`["facebook", "instagram"]` 会返回来自任一平台的帖子。
</ParamField>

<ParamField query="startDate" type="string">
  返回自该起始日期起（含）之后的帖子。以 ISO 8601 格式表示历史记录的起始日期。
  例如，使用 `YYYY-MM-DDThh:mm:ssZ` 格式发送，如 `2026-07-08T12:30:00Z`。更多示例请参见
  [utctime](https://www.utctime.net/)。
</ParamField>

<ParamField query="endDate" type="string">
  返回直到该结束日期（含）的帖子。以 ISO 8601 格式表示历史记录的结束日期。
  例如，使用 `YYYY-MM-DDThh:mm:ssZ` 格式发送，如 `2026-07-08T12:30:00Z`。更多示例请参见
  [utctime](https://www.utctime.net/)。
</ParamField>

<ParamField query="lastDays" type="number" default={30}>
  按发布日期（即 `scheduleDate`）返回最近 n 天的帖子。默认 30 天。

  <ul class="custom-bullets">
    <li>如果提供了 `startDate` 和 `endDate`，`lastDays` 将被忽略。</li>
    <li>如果值为 0，将返回全部历史帖子。</li>
    <li>如果值大于 0，将返回最近 n 天的帖子。</li>

    <li>
      例如，`lastDays=5` 返回最近 5 天的帖子；`lastDays=0` 则返回受 `limit` 限制的所有帖子。
    </li>
  </ul>
</ParamField>

<ParamField query="status" type="string">
  按帖子当前状态筛选。有效取值：`success`、`error`、`processing`、`pending`、`paused`、`deleted` 和 `awaiting approval`。
  processing 表示帖子正在发送中。pending 表示帖子已定时于未来某个日期发布。

  <Info>
    删除的帖子默认不会返回。只有在 status 查询过滤条件设置为 `status=deleted` 时才会返回。
  </Info>
</ParamField>

<ParamField query="type" type="string">
  要检索的帖子类型，即立即发布的帖子或使用 `scheduleDate` 字段的定时帖子。取值：`immediate` 或 `scheduled`。
</ParamField>

<ParamField query="autoRepostId" type="string">
  创建自动转发帖时会分配一个 ID 用于追踪该系列帖子。
  通过 auto repost ID 检索帖子，或使用 `all` 获取所有自动转发帖。
</ParamField>

<RequestExample>
  ```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}");
              }
          }
      }
  }
  }
  ```
</RequestExample>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>