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

> Pull live daily Google Ads metrics for your campaigns, ad groups or ads, with clicks, cost, conversions and conversion value.

Get live Google Ads performance, one row per day, for the campaigns, ad groups or ads you created through Ayrshare.

<ul>
  <li>Numbers are read from Google when you call, not from a nightly copy.</li>
  <li>All money values are in the ad account's currency, returned in `currency` on each row.</li>
  <li>Google leaves out days with no activity, so a range can return fewer rows than it has days.</li>
  <li>Google adjusts a day's cost and conversions for a few days after it ends, so recent days can change between reads.</li>
  <li>For a Performance Max campaign, use `level=campaign` with the campaign id. A Performance Max campaign has no ads of its own, so `level=ad` returns no rows.</li>
</ul>

## Header Parameters

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

## Query Parameters

**level** `string` *required*

What each row reports on: `campaign` (the `campaignId` from Create), `adSet` (the `adGroupId` from Create) or `ad` (the `adId` from Create).

**ids** `string` *required*

Comma-separated campaign, ad group or ad ids, up to 50. They must all be in one ad account.

**accountId** `string`

The 10-digit Google Ads customer id, with or without hyphens (`123-456-7890`).

Ad and ad group reports read the ad account you name here. Without it, an ad report searches every ad account your Google Ads link reaches, up to 25, and an ad group report works only when your link reaches one ad account. Name the account when your link reaches more than 25 ad accounts, or more than one for an ad group report. Otherwise the request answers `code: 101`.

**metrics** `string`

Comma-separated metrics to return. Leave it out to get them all. See [Metrics](#metrics).

**startDate** `string` (default: 30 days ago)

First day, as `YYYY-MM-DD`. Google keeps daily numbers for 37 months; an older `startDate` answers `code: 101`.

**endDate** `string` (default: today)

Last day, as `YYYY-MM-DD`.

## Metrics

| Metric | Type | Meaning |
| - | - | - |
| `spend` | number | Amount spent |
| `impressions` | number | Times the ad was shown |
| `clicks` | number | Clicks |
| `cpm` | number or `null` | Cost per 1,000 impressions. `null` on a day with no impressions |
| `cpc` | number or `null` | Cost per click. `null` on a day with no clicks |
| `ctr` | number or `null` | Click-through rate, in percent. `null` on a day with no impressions |
| `actions` | number | Google's conversions, which can be fractional |
| `conversionValue` | number | The value of those conversions |

`actions` and `conversionValue` stay `0` until conversion tracking is set up in your Google Ads account. `reach` is not available, because Google reports no unique reach for Search, and `breakdowns` are not available on Google. Asking for either answers `code: 101`.

## Paging

Every row comes back in one response, so `nextCursor` is always `null`.

## Errors

| Code | When |
| - | - |
| `101` | A parameter is missing or wrong, a metric or breakdown isn't supported, `startDate` is more than 37 months ago, more than 50 ids are sent, the ids are in more than one ad account, or `accountId` is needed and missing |
| `400` | A campaign, ad group or ad isn't yours, or `accountId` isn't the ad account Ayrshare has on record for the ids you sent |
| `370` | Google could not return the insights. Try again |

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