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

# Insights

> Отримуйте щоденні показники Google Ads у реальному часі для ваших кампаній, груп оголошень або оголошень, із кліками, вартістю, конверсіями та їхньою цінністю.

Отримуйте ефективність Google Ads у реальному часі, по одному рядку за день, для кампаній, груп оголошень або оголошень, створених через Ayrshare.

<ul>
  <li>Дані зчитуються з Google в момент вашого запиту, а не з нічної копії.</li>
  <li>Усі грошові значення подаються у валюті рекламного облікового запису, яка повертається в `currency` у кожному рядку.</li>
  <li>Google пропускає дні без активності, тому діапазон може повернути менше рядків, ніж у ньому днів.</li>
  <li>Google коригує вартість і конверсії за день ще кілька днів після його завершення, тому дані за останні дні можуть змінюватися між запитами.</li>
  <li>Для кампанії Performance Max використовуйте `level=campaign` з ID кампанії. Кампанія Performance Max не має власних оголошень, тому `level=ad` не повертає рядків.</li>
</ul>

## Параметри заголовка

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

## Параметри запиту

**level** `string` *required*

Про що звітує кожен рядок: `campaign` (`campaignId`, отриманий під час створення), `adSet` (`adGroupId`, отриманий під час створення) або `ad` (`adId`, отриманий під час створення).

**ids** `string` *required*

ID кампаній, груп оголошень або оголошень через кому, до 50. Усі вони мають належати до одного рекламного облікового запису.

**accountId** `string`

10-значний ID клієнта Google Ads, із дефісами або без них (`123-456-7890`).

Звіти за оголошеннями та групами оголошень зчитують рекламний обліковий запис, указаний тут. Без нього звіт за оголошеннями шукає в усіх рекламних облікових записах, до яких має доступ ваше під'єднання Google Ads, але не більше ніж у 25, а звіт за групами оголошень працює лише тоді, коли ваше під'єднання має доступ до одного рекламного облікового запису. Укажіть обліковий запис, коли ваше під'єднання має доступ до понад 25 рекламних облікових записів або до понад одного для звіту за групами оголошень. Інакше запит повертає `code: 101`.

**metrics** `string`

Метрики для повернення через кому. Не передавайте цей параметр, щоб отримати всі. Див. [Метрики](#metrics).

**startDate** `string` (default: 30 днів тому)

Перший день у форматі `YYYY-MM-DD`. Google зберігає щоденні показники протягом 37 місяців; ранніша `startDate` повертає `code: 101`.

**endDate** `string` (default: сьогодні)

Останній день у форматі `YYYY-MM-DD`.

## Метрики

| Метрика | Тип | Значення |
| - | - | - |
| `spend` | number | Витрачена сума |
| `impressions` | number | Скільки разів оголошення було показано |
| `clicks` | number | Кліки |
| `cpm` | number або `null` | Вартість за 1 000 показів. `null` у день без показів |
| `cpc` | number або `null` | Вартість за клік. `null` у день без кліків |
| `ctr` | number або `null` | Показник клікабельності, у відсотках. `null` у день без показів |
| `actions` | number | Конверсії Google, які можуть бути дробовими |
| `conversionValue` | number | Цінність цих конверсій |

`actions` і `conversionValue` дорівнюють `0`, доки у вашому обліковому записі Google Ads не налаштовано відстеження конверсій. `reach` недоступний, бо Google не повідомляє унікальне охоплення для Search, а `breakdowns` недоступні в Google. Запит будь-якого з них повертає `code: 101`.

## Пагінація

Усі рядки повертаються в одній відповіді, тому `nextCursor` завжди має значення `null`.

## Помилки

| Код | Коли |
| - | - |
| `101` | Параметр відсутній або неправильний, метрика чи розбивка не підтримується, `startDate` більш ніж 37 місяців тому, надіслано понад 50 ID, ID належать до кількох рекламних облікових записів або `accountId` потрібен, але відсутній |
| `400` | Кампанія, група оголошень чи оголошення не належить вам, або `accountId` не є рекламним обліковим записом, який Ayrshare має в записах для надісланих ID |
| `370` | Google не зміг повернути аналітику. Спробуйте ще раз |

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07"
```

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

fetch("https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07", {
  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/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07", 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/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    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/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07");
        var content = await response.Content.ReadAsStringAsync();

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

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

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

func main() {
    req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07", nil)
    req.Header.Add("Authorization", "Bearer API_KEY")

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

    body, _ := io.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 GetAdInsights {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07"))
            .header("Authorization", "Bearer API_KEY")
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

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

uri = URI.parse('https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07')

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

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

puts response.body
```

```json 200: Success theme={"system"}
{
  "status": "success",
  "platform": "google",
  "level": "campaign",
  "startDate": "2026-10-01",
  "endDate": "2026-10-07",
  "insights": [
    {
      "date": "2026-10-01",
      "level": "campaign",
      "id": "21534567890",
      "currency": "USD",
      "spend": 12.48,
      "impressions": 1830,
      "clicks": 41,
      "cpm": 6.82,
      "cpc": 0.3,
      "ctr": 2.2404,
      "actions": 3.5,
      "conversionValue": 140
    }
  ],
  "count": 1,
  "nextCursor": null
}
```


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