Get historical keyword metrics

curl --request POST \
  --url https://api.aisa.one/apis/v1/ads/keywords/historical-metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keywords": [
    "example"
  ]
}
'

import requests

url = "https://api.aisa.one/apis/v1/ads/keywords/historical-metrics"

payload = { "keywords": ["example"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({keywords: ['example']})
};

fetch('https://api.aisa.one/apis/v1/ads/keywords/historical-metrics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/keywords/historical-metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'keywords' => [
        'example'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.aisa.one/apis/v1/ads/keywords/historical-metrics"

	payload := strings.NewReader("{\n  \"keywords\": [\n    \"example\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/ads/keywords/historical-metrics")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"keywords\": [\n    \"example\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads/keywords/historical-metrics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"keywords\": [\n    \"example\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "aggregateMetricResults": {},
  "customerId": "<string>",
  "data": [
    {}
  ]
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

AIsa Ads

Get historical keyword metrics

Ad Insights. Read only. Gets historical search volume, competition and bid ranges for up to 1,000 keywords from Google Keyword Planner. Google Ads only. Runs Keyword Planner's generateKeywordHistoricalMetrics for up to 1,000 exact keywords: historical search volume, competition and top-of-page bid ranges, plus averageCpcMicros when includeAverageCpc is set.  A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.

POST

https://api.aisa.one

apis

ads

keywords

historical-metrics

Get historical keyword metrics

curl --request POST \
  --url https://api.aisa.one/apis/v1/ads/keywords/historical-metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keywords": [
    "example"
  ]
}
'

import requests

url = "https://api.aisa.one/apis/v1/ads/keywords/historical-metrics"

payload = { "keywords": ["example"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({keywords: ['example']})
};

fetch('https://api.aisa.one/apis/v1/ads/keywords/historical-metrics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/keywords/historical-metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'keywords' => [
        'example'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.aisa.one/apis/v1/ads/keywords/historical-metrics"

	payload := strings.NewReader("{\n  \"keywords\": [\n    \"example\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/ads/keywords/historical-metrics")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"keywords\": [\n    \"example\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads/keywords/historical-metrics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"keywords\": [\n    \"example\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "aggregateMetricResults": {},
  "customerId": "<string>",
  "data": [
    {}
  ]
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

Request contract

Method and path: POST /apis/v1/ads/keywords/historical-metrics
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/ads/keywords/historical-metrics
connectionId: query; required
Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "post_aisa_ads_apis_v1_ads_keywords_historical_metrics",
  "method": "POST",
  "path": "/apis/v1/ads/keywords/historical-metrics",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [
    {
      "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
      "in": "query",
      "name": "connectionId",
      "required": true,
      "schema": {
        "pattern": "^adc_[0-9A-Za-z]+$",
        "type": "string"
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "example": {
          "connectionId": "adc_7f3k2m9q",
          "keywords": [
            "example"
          ]
        },
        "schema": {
          "additionalProperties": true,
          "properties": {
            "adAccountId": {
              "description": "Platform ad account ID (Google customer ID, digits only).",
              "type": "string"
            },
            "connectionId": {
              "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.",
              "pattern": "^adc_[0-9A-Za-z]+$",
              "type": "string"
            },
            "countries": {
              "description": "ISO 3166-1 alpha-2 country codes. Omitted = worldwide.",
              "items": {
                "maxLength": 2,
                "minLength": 2,
                "type": "string"
              },
              "maxItems": 10,
              "minItems": 1,
              "type": "array"
            },
            "customerId": {
              "description": "Alias of adAccountId, kept for existing callers",
              "type": "string"
            },
            "includeAdultKeywords": {
              "type": "boolean"
            },
            "includeAverageCpc": {
              "description": "Adds averageCpcMicros to each row's keywordMetrics.",
              "type": "boolean"
            },
            "keywords": {
              "items": {
                "maxLength": 80,
                "type": "string"
              },
              "maxItems": 1000,
              "minItems": 1,
              "type": "array"
            },
            "languageConstantId": {
              "default": "1000",
              "description": "Google languageConstant id (1000 = English).",
              "type": "string"
            },
            "network": {
              "default": "GOOGLE_SEARCH",
              "enum": [
                "GOOGLE_SEARCH",
                "GOOGLE_SEARCH_AND_PARTNERS"
              ],
              "type": "string"
            }
          },
          "required": [
            "keywords"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
    "kind": "no_customer_charge"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

connectionId

string

required

The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.

Pattern: ^adc_[0-9A-Za-z]+$

Body

application/json

keywords

string[]

required

Required array length: 1 - 1000 elements

Maximum string length: 80

adAccountId

string

Platform ad account ID (Google customer ID, digits only).

connectionId

string

The ads connection (adc_...), when not sent as the connectionId query parameter.

Pattern: ^adc_[0-9A-Za-z]+$

countries

string[]

ISO 3166-1 alpha-2 country codes. Omitted = worldwide.

Required array length: 1 - 10 elements

Required string length: 2

customerId

string

Alias of adAccountId, kept for existing callers

includeAdultKeywords

boolean

includeAverageCpc

boolean

Adds averageCpcMicros to each row's keywordMetrics.

languageConstantId

string

default:1000

Google languageConstant id (1000 = English).

network

enum<string>

default:GOOGLE_SEARCH

Available options:

GOOGLE_SEARCH,

GOOGLE_SEARCH_AND_PARTNERS

Response

Historical metric rows (raw Keyword Planner shape)

aggregateMetricResults

object | null

customerId

string

The customer the request ran against.

data

object[]

​Request contract

​Cost and request rules

Authorizations

Query Parameters

Body

Response

Request contract

Cost and request rules