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

# Historial

> Obtener el gasto diario histórico y analíticas de anuncios de 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} />

Recupera métricas detalladas de gasto diario en anuncios y de rendimiento para tus anuncios de Instagram.
Este endpoint proporciona analíticas completas de tus anuncios con desgloses diarios, rendimiento por objetivo y métricas agregadas.

<Tip>
  El arreglo `history` contiene el gasto diario histórico y las métricas de rendimiento
  para cada anuncio. Los datos son al corte de las 8 AM EST. Si necesitas datos de gasto en tiempo real o el gasto aún no ha ocurrido,
  por favor usa el [endpoint de anuncios](/docs/apis/ads/instagram/get-boosted-ads).

  El anuncio **NO** será devuelto si no hay datos de gasto disponibles o si el gasto aún no ha ocurrido.

  Cuando ningún anuncio tiene gasto en el rango de fechas, la respuesta sigue siendo exitosa: `history` está
  vacío y `warnings` contiene una entrada con el código `401`.
</Tip>

<ul className="custom-bullets">
  <li>
    Las métricas se calculan a partir de la API de informes de Instagram y pueden tener ligeros retrasos (hasta 24
    horas).
  </li>

  <li>Las secciones `byGoalType` y `byGoalTitle` agrupan las métricas de rendimiento por objetivos.</li>
  <li>Usa los filtros `adId` o `postId` para acotar los resultados a campañas específicas.</li>
  <li>Todos los valores monetarios están en la moneda de la cuenta publicitaria (típicamente USD).</li>
  <li>La sección `goalPerformance` destaca tus objetivos publicitarios con mejor rendimiento.</li>
</ul>

## Parámetros del encabezado

<HeaderAPI />

## Parámetros de consulta

<ParamField query="accountId" type="string">
  Filtra los resultados a un ID de cuenta específico.
</ParamField>

<ParamField query="adId" type="string">
  Filtra los resultados a un ID de anuncio específico.
</ParamField>

<ParamField query="postId" type="string">
  Filtra los resultados a anuncios asociados con un [ID de publicación de
  Ayrshare](/docs/apis/overview#ayrshare-post-id) específico.
</ParamField>

<ParamField query="socialPostId" type="string">
  Filtra los resultados a anuncios asociados con un [ID de publicación social de
  Instagram](/docs/apis/overview#social-post-id) específico.
</ParamField>

<ParamField query="limit" type="number" default={25}>
  Recupera un máximo de `limit` anuncios. El máximo es 300; los valores superiores se limitan a 300.
</ParamField>

<ParamField query="startDate" type="string" default="hace 30 días">
  Fecha de inicio del periodo de informe en formato ISO 8601 (predeterminado: hace 30 días)
</ParamField>

<ParamField query="endDate" type="string" default="hoy">
  Fecha de finalización del periodo de informe en formato ISO 8601 (predeterminado: hoy)
</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: Éxito sin parámetro 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": 1.01,
          "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": 1.02,
          "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": 1.02,
      "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: Éxito por ID de anuncio 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": 1.03,
          "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": 1,
          "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": 1.02,
      "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 200: No spend data theme={"system"}
  {
    "status": "success",
    "history": [],
    "dateRange": {
      "start": "2025-03-04T18:49:18.159Z",
      "end": "2025-04-03T18:49:18.159Z",
      "adId": "6683876017505"
    },
    "metrics": {
      "totalSpend": 0,
      "totalClicks": 0,
      "totalImpressions": 0,
      "totalReach": 0,
      "averageCTR": 0,
      "averageFrequency": 0,
      "cpm": 0,
      "cpp": 0,
      "cpc": 0,
      "costPerResult": 0,
      "byGoalType": {},
      "byGoalTitle": {},
      "goalPerformance": {
        "bestPerformingGoalType": null,
        "mostEfficientGoalType": null
      },
      "daysCount": 0,
      "firstDay": null,
      "lastDay": null
    },
    "warnings": [
      {
        "action": "ads",
        "status": "error",
        "code": 401,
        "message": "No spend data found for the ad."
      }
    ]
  }
  ```

  ```json 400: Error de gasto publicitario 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>


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