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

# السجل

> الحصول على الإنفاق اليومي التاريخي والتحليلات لإعلانات Instagram

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="/docs/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="/docs/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="/docs/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} />

استرجع مقاييس الإنفاق اليومي المفصّل والأداء لإعلاناتك على Instagram.
تقدّم هذه النقطة الطرفية تحليلات شاملة لإعلاناتك مع تفصيل يومي، وأداء خاص بكل هدف، ومقاييس مجمّعة.

<Tip>
  تحتوي مصفوفة `history` على مقاييس الإنفاق والأداء اليومي التاريخي
  لكل إعلان. البيانات محدَّثة حتى الساعة 8 صباحًا بتوقيت شرق الولايات المتحدة (EST). إذا كنت بحاجة إلى بيانات إنفاق آنية أو لم يبدأ الإنفاق بعد،
  يُرجى استخدام [نقطة نهاية الإعلانات](/docs/apis/ads/instagram/get-boosted-ads).

  **لن** يُعاد الإعلان إذا لم تتوفر بيانات إنفاق أو لم يبدأ الإنفاق بعد.
</Tip>

<ul className="custom-bullets">
  <li>
    تُحسب المقاييس من واجهة تقارير Instagram وقد يكون هناك تأخير طفيف (حتى 24
    ساعة).
  </li>

  <li>يُجمِّع القسمان `byGoalType` و`byGoalTitle` مقاييس الأداء حسب أهداف الحملة.</li>
  <li>استخدم مرشحات `adId` أو `postId` لتضييق النتائج على حملات محددة.</li>
  <li>جميع القيم النقدية بعملة حساب الإعلانات (الدولار الأمريكي عادةً).</li>
  <li>يُبرز القسم `goalPerformance` أهداف الإعلانات الأفضل أداءً لديك.</li>
</ul>

## معاملات الترويسة

<HeaderAPI />

## معاملات الاستعلام

<ParamField query="accountId" type="number">
  تصفية النتائج حسب معرّف حساب محدد.
</ParamField>

<ParamField query="adId" type="string">
  تصفية النتائج حسب معرّف إعلان محدد.
</ParamField>

<ParamField query="postId" type="string">
  تصفية النتائج للإعلانات المرتبطة بمعرّف [منشور Ayrshare
  محدد](/docs/apis/overview#ayrshare-post-id).
</ParamField>

<ParamField query="socialPostId" type="string">
  تصفية النتائج للإعلانات المرتبطة بمعرّف [منشور Instagram الاجتماعي
  محدد](/docs/apis/overview#social-post-id).
</ParamField>

<ParamField query="limit" type="number" default={25}>
  استرجع حدًا أقصى `limit` من الإعلانات. الحد الأقصى 300؛ وتُخفَّض القيم الأعلى إلى 300.
</ParamField>

<ParamField query="startDate" type="string" default="30 days ago">
  تاريخ بداية فترة إعداد التقارير بصيغة ISO 8601 (الافتراضي: 30 يومًا مضت)
</ParamField>

<ParamField query="endDate" type="string" default="today">
  تاريخ نهاية فترة إعداد التقارير بصيغة ISO 8601 (الافتراضي: اليوم)
</ParamField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET https://api.ayrshare.com/api/ads/instagram/history?accountId=1234567890
  ```

  ```javascript JavaScript theme={"system"}
  const API_KEY = "API_KEY";

  fetch("https://api.ayrshare.com/api/ads/instagram/history?accountId=1234567890", {
        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/ads/instagram/history', headers=headers)

  print(r.json())
  ```

  ```php PHP theme={"system"}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => "https://api.ayrshare.com/api/ads/instagram/history",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer API_KEY"
      ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
      echo "cURL Error: " . $err;
  } else {
      echo $response;
  }
  ?>
  ```

  ```csharp C# theme={"system"}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");

          var response = await client.GetAsync("https://api.ayrshare.com/api/ads/instagram/history");
          var content = await response.Content.ReadAsStringAsync();

          Console.WriteLine(content);
      }
  }
  ```

  ```go Go theme={"system"}
  package main

  import (
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      client := &http.Client{}
      req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/instagram/history", nil)

      req.Header.Add("Authorization", "Bearer API_KEY")

      resp, err := client.Do(req)
      if err != nil {
          fmt.Println("Error:", err)
          return
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={"system"}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class GetAdSpend {
      public static void main(String[] args) {
          HttpClient client = HttpClient.newHttpClient();

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.ayrshare.com/api/ads/instagram/history"))
              .header("Authorization", "Bearer API_KEY")
              .GET()
              .build();

          try {
              HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
              System.out.println(response.body());
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  ```

  ```ruby Ruby theme={"system"}
  require 'net/http'
  require 'json'
  require 'uri'

  uri = URI.parse('https://api.ayrshare.com/api/ads/instagram/history')

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer API_KEY'

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
    http.request(request)
  end

  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success No Param theme={"system"}
  {
    "status": "success",
    "history": [
      {
        "adId": "6683876017501",
        "adName": "API Post 1 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
        "budgetDaily": 4,
        "budgetType": "daily",
        "deliveryStatus": "ACTIVE",
        "goal": {
          "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
          "title": "Get More Engagement",
          "type": "engagement"
        },
        "isActive": true,
        "isComplete": false,
        "metrics": {
          "clicks": 3,
          "impressions": 1035,
          "reach": 1026,
          "frequency": 0,
          "ctr": 0.29,
          "cpm": 1.53,
          "cpp": 1.54,
          "cpc": 0.53
        },
        "network": "instagram",
        "postId": "DE6gpw8kxlonHy6eb7L1",
        "spend": 1.58,
        "spendDate": "2025-04-02T00:00:00.000Z",
        "status": "ACTIVE",
        "accountId": "274948332"
      },
      {
        "adId": "120218167147110411",
        "adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
        "budgetDaily": 4,
        "budgetType": "daily",
        "deliveryStatus": "ACTIVE",
        "goal": {
          "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
          "title": "Get More Engagement",
          "type": "engagement"
        },
        "isActive": true,
        "isComplete": false,
        "metrics": {
          "clicks": 4,
          "impressions": 1036,
          "reach": 1011,
          "frequency": 0,
          "ctr": 0.39,
          "cpm": 1.61,
          "cpp": 1.65,
          "cpc": 0.42
        },
        "network": "instagram",
        "postId": "DE6gpw8kxlonHy6eb7L1",
        "spend": 1.67,
        "spendDate": "2025-04-02T00:00:00.000Z",
        "status": "ACTIVE",
        "accountId": "274948332"
      }
    ],
    "dateRange": {
      "start": "2025-03-04T18:49:18.159Z",
      "end": "2025-04-03T18:49:18.159Z"
    },
    "metrics": {
      "totalSpend": 3.25,
      "totalClicks": 7,
      "totalImpressions": 2071,
      "totalReach": 2037,
      "averageCTR": 0.34,
      "averageFrequency": 0.0,
      "cpm": 1.57,
      "cpp": 1.6,
      "cpc": 0.46,
      "costPerResult": 0.46,
      "byGoalType": {
        "engagement": {
          "spend": 3.25,
          "impressions": 2071,
          "clicks": 7,
          "reach": 2037,
          "count": 2,
          "ctr": 0.3380009657170449,
          "cpm": 1.5692901979719942,
          "cpp": 1.5954835542464407,
          "cpc": 0.4642857142857143
        }
      },
      "byGoalTitle": {
        "Get More Engagement": {
          "spend": 3.25,
          "impressions": 2071,
          "clicks": 7,
          "reach": 2037,
          "count": 2,
          "ctr": 0.3380009657170449,
          "cpm": 1.5692901979719942,
          "cpp": 1.5954835542464407,
          "cpc": 0.4642857142857143,
          "type": "engagement"
        }
      },
      "goalPerformance": {
        "bestPerformingGoalType": {
          "type": "engagement",
          "clicks": 7,
          "spend": 3.25,
          "ctr": 0.34
        },
        "mostEfficientGoalType": {
          "type": "engagement",
          "cpc": 0.46,
          "spend": 3.25
        }
      },
      "count": 2,
      "firstDay": "2025-04-02T00:00:00.000Z",
      "lastDay": "2025-04-02T00:00:00.000Z"
    }
  }
  ```

  ```json 200: Success by Ad ID theme={"system"}
  {
    "status": "success",
    "history": [
      {
        "accountId": "274948332",
        "adId": "6683876017505",
        "adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
        "budgetDaily": 4,
        "budgetType": "",
        "deliveryStatus": "ACTIVE",
        "socialPostId": "17890000000000001",
        "goal": {
          "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
          "title": "Get More Engagement",
          "type": "engagement"
        },
        "isActive": true,
        "isComplete": false,
        "metrics": {
          "clicks": 2,
          "cpc": 0.35,
          "cpp": 1.6,
          "cpm": 1.55,
          "ctr": 0.44,
          "frequency": 0,
          "impressions": 452,
          "reach": 438
        },
        "network": "instagram",
        "postId": "DE6gpw8kxlonHy6eb7Lo",
        "spend": 0.7,
        "spendDate": "2025-04-03T00:00:00.000Z",
        "status": "ACTIVE",
        "igPostId": "17890000000000001"
      },
      {
        "accountId": "274948332",
        "adId": "6683876017505",
        "adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
        "budgetDaily": 4,
        "budgetType": "daily",
        "deliveryStatus": "ACTIVE",
        "socialPostId": "17890000000000001",
        "goal": {
          "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
          "title": "Get More Engagement",
          "type": "engagement"
        },
        "isActive": true,
        "isComplete": false,
        "metrics": {
          "clicks": 1,
          "cpc": 4.19,
          "cpp": 1.5,
          "cpm": 1.5,
          "ctr": 0.04,
          "frequency": 0,
          "impressions": 2793,
          "reach": 2793
        },
        "network": "instagram",
        "postId": "DE6gpw8kxlonHy6eb7Lo",
        "spend": 4.19,
        "spendDate": "2025-04-02T00:00:00.000Z",
        "status": "ACTIVE",
        "igPostId": "17890000000000001"
      }
    ],
    "dateRange": {
      "start": "2025-03-04T18:49:18.159Z",
      "end": "2025-04-03T18:49:18.159Z",
      "adId": "6683876017505"
    },
    "metrics": {
      "totalSpend": 4.89,
      "totalClicks": 3,
      "totalImpressions": 3245,
      "totalReach": 3231,
      "averageCTR": 0.09,
      "averageFrequency": 0.0,
      "cpm": 1.51,
      "cpp": 1.51,
      "cpc": 1.63,
      "costPerResult": 1.63,
      "byGoalType": {
        "engagement": {
          "spend": 4.890000000000001,
          "impressions": 3245,
          "clicks": 3,
          "reach": 3231,
          "count": 2,
          "ctr": 0.09244992295839753,
          "cpm": 1.50693374422188,
          "cpp": 1.5134633240482824,
          "cpc": 1.6300000000000001
        }
      },
      "byGoalTitle": {
        "Get More Engagement": {
          "spend": 4.890000000000001,
          "impressions": 3245,
          "clicks": 3,
          "reach": 3231,
          "count": 2,
          "ctr": 0.09244992295839753,
          "cpm": 1.50693374422188,
          "cpp": 1.5134633240482824,
          "cpc": 1.6300000000000001,
          "type": "engagement"
        }
      },
      "goalPerformance": {
        "bestPerformingGoalType": {
          "type": "engagement",
          "clicks": 3,
          "spend": 4.89,
          "ctr": 0.09
        },
        "mostEfficientGoalType": {
          "type": "engagement",
          "cpc": 1.63,
          "spend": 4.89
        }
      },
      "count": 2,
      "firstDay": "2025-04-02T00:00:00.000Z",
      "lastDay": "2025-04-03T00:00:00.000Z"
    }
  }
  ```

  ```json 400: Ad spend error theme={"system"}
  {
    "action": "ads",
    "status": "error",
    "code": 370,
    "message": "Error getting ads. Please try again or contact us if the issue persists.",
    "details": "Error retrieving ads spend data"
  }
  ```
</ResponseExample>