> ## 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>
    如果只需要單一貼文，請使用 [post history by
    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">
  建立自動重發 (auto repost) 時，系統會指派一個 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>