Pesquisa de SEO

curl --request POST \
  --url https://api.glasser.ai/v1/solutions/gtm/seo_research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "use_case": "<string>",
  "keywords": [
    "<string>"
  ],
  "domain": "<string>",
  "competitors": [
    "<string>"
  ],
  "url": "<string>",
  "country": "<string>",
  "limit": 50,
  "task_id": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.glasser.ai/v1/solutions/gtm/seo_research"

payload = {
    "use_case": "<string>",
    "keywords": ["<string>"],
    "domain": "<string>",
    "competitors": ["<string>"],
    "url": "<string>",
    "country": "<string>",
    "limit": 50,
    "task_id": "<string>",
    "metadata": {}
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    use_case: '<string>',
    keywords: ['<string>'],
    domain: '<string>',
    competitors: ['<string>'],
    url: '<string>',
    country: '<string>',
    limit: 50,
    task_id: '<string>',
    metadata: {}
  })
};

fetch('https://api.glasser.ai/v1/solutions/gtm/seo_research', 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.glasser.ai/v1/solutions/gtm/seo_research",
  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([
    'use_case' => '<string>',
    'keywords' => [
        '<string>'
    ],
    'domain' => '<string>',
    'competitors' => [
        '<string>'
    ],
    'url' => '<string>',
    'country' => '<string>',
    'limit' => 50,
    'task_id' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$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.glasser.ai/v1/solutions/gtm/seo_research"

	payload := strings.NewReader("{\n  \"use_case\": \"<string>\",\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"domain\": \"<string>\",\n  \"competitors\": [\n    \"<string>\"\n  ],\n  \"url\": \"<string>\",\n  \"country\": \"<string>\",\n  \"limit\": 50,\n  \"task_id\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("idempotency-key", "<idempotency-key>")
	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.glasser.ai/v1/solutions/gtm/seo_research")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"use_case\": \"<string>\",\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"domain\": \"<string>\",\n  \"competitors\": [\n    \"<string>\"\n  ],\n  \"url\": \"<string>\",\n  \"country\": \"<string>\",\n  \"limit\": 50,\n  \"task_id\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.glasser.ai/v1/solutions/gtm/seo_research")

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

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"use_case\": \"<string>\",\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"domain\": \"<string>\",\n  \"competitors\": [\n    \"<string>\"\n  ],\n  \"url\": \"<string>\",\n  \"country\": \"<string>\",\n  \"limit\": 50,\n  \"task_id\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "id": "<string>",
  "run_url": "<string>",
  "provider": "<string>",
  "endpoint": "<string>",
  "endpoint_version": 123,
  "status": "QUEUED",
  "failure": {
    "kind": "TIMED_OUT",
    "message": "<string>"
  },
  "input": {},
  "output": {
    "items": [
      {
        "keyword": "<string>",
        "volume": 123,
        "cpc_usd": 123,
        "semrush_keyword_difficulty": 123,
        "serpstat_keyword_difficulty": 123,
        "dataforseo_keyword_difficulty": 123,
        "ahrefs_keyword_difficulty": 123,
        "intent": "<string>"
      }
    ]
  },
  "provider_response": {
    "http_status": 349,
    "error": null
  },
  "charge_usd": "<string>",
  "charge_basis": {
    "clause": "rule",
    "quantity": 1
  },
  "stoppable": true,
  "stop_requested_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "task_id": "<string>",
  "metadata": {},
  "action": "keyword_overview",
  "result_status": "success",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "runs": [
    {
      "id": "<string>",
      "run_url": "<string>",
      "provider": "<string>",
      "endpoint": "<string>",
      "endpoint_version": 123,
      "status": "QUEUED",
      "failure": {
        "kind": "TIMED_OUT",
        "message": "<string>"
      },
      "input": {
        "omitted": true
      },
      "output": {
        "omitted": true
      },
      "provider_response": {
        "http_status": 349
      },
      "charge_usd": "<string>",
      "charge_basis": {
        "clause": "rule",
        "quantity": 1
      },
      "stoppable": true,
      "stop_requested_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "task_id": "<string>",
      "metadata": {}
    }
  ],
  "result_url": "<string>"
}

{
  "id": "<string>",
  "run_url": "<string>",
  "provider": "<string>",
  "endpoint": "<string>",
  "endpoint_version": 123,
  "status": "QUEUED",
  "failure": {
    "kind": "TIMED_OUT",
    "message": "<string>"
  },
  "input": {},
  "output": {
    "items": [
      {
        "keyword": "<string>",
        "volume": 123,
        "cpc_usd": 123,
        "semrush_keyword_difficulty": 123,
        "serpstat_keyword_difficulty": 123,
        "dataforseo_keyword_difficulty": 123,
        "ahrefs_keyword_difficulty": 123,
        "intent": "<string>"
      }
    ]
  },
  "provider_response": {
    "http_status": 349,
    "error": null
  },
  "charge_usd": "<string>",
  "charge_basis": {
    "clause": "rule",
    "quantity": 1
  },
  "stoppable": true,
  "stop_requested_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "task_id": "<string>",
  "metadata": {},
  "action": "keyword_overview",
  "result_status": "success",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "runs": [
    {
      "id": "<string>",
      "run_url": "<string>",
      "provider": "<string>",
      "endpoint": "<string>",
      "endpoint_version": 123,
      "status": "QUEUED",
      "failure": {
        "kind": "TIMED_OUT",
        "message": "<string>"
      },
      "input": {
        "omitted": true
      },
      "output": {
        "omitted": true
      },
      "provider_response": {
        "http_status": 349
      },
      "charge_usd": "<string>",
      "charge_basis": {
        "clause": "rule",
        "quantity": 1
      },
      "stoppable": true,
      "stop_requested_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "task_id": "<string>",
      "metadata": {}
    }
  ],
  "result_url": "<string>"
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "endpoint_not_permitted",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "rate_limited",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "service_unavailable",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

POST

solutions

gtm

seo_research

Pesquisa de SEO

curl --request POST \
  --url https://api.glasser.ai/v1/solutions/gtm/seo_research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "use_case": "<string>",
  "keywords": [
    "<string>"
  ],
  "domain": "<string>",
  "competitors": [
    "<string>"
  ],
  "url": "<string>",
  "country": "<string>",
  "limit": 50,
  "task_id": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.glasser.ai/v1/solutions/gtm/seo_research"

payload = {
    "use_case": "<string>",
    "keywords": ["<string>"],
    "domain": "<string>",
    "competitors": ["<string>"],
    "url": "<string>",
    "country": "<string>",
    "limit": 50,
    "task_id": "<string>",
    "metadata": {}
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    use_case: '<string>',
    keywords: ['<string>'],
    domain: '<string>',
    competitors: ['<string>'],
    url: '<string>',
    country: '<string>',
    limit: 50,
    task_id: '<string>',
    metadata: {}
  })
};

fetch('https://api.glasser.ai/v1/solutions/gtm/seo_research', 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.glasser.ai/v1/solutions/gtm/seo_research",
  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([
    'use_case' => '<string>',
    'keywords' => [
        '<string>'
    ],
    'domain' => '<string>',
    'competitors' => [
        '<string>'
    ],
    'url' => '<string>',
    'country' => '<string>',
    'limit' => 50,
    'task_id' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$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.glasser.ai/v1/solutions/gtm/seo_research"

	payload := strings.NewReader("{\n  \"use_case\": \"<string>\",\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"domain\": \"<string>\",\n  \"competitors\": [\n    \"<string>\"\n  ],\n  \"url\": \"<string>\",\n  \"country\": \"<string>\",\n  \"limit\": 50,\n  \"task_id\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("idempotency-key", "<idempotency-key>")
	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.glasser.ai/v1/solutions/gtm/seo_research")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"use_case\": \"<string>\",\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"domain\": \"<string>\",\n  \"competitors\": [\n    \"<string>\"\n  ],\n  \"url\": \"<string>\",\n  \"country\": \"<string>\",\n  \"limit\": 50,\n  \"task_id\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.glasser.ai/v1/solutions/gtm/seo_research")

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

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"use_case\": \"<string>\",\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"domain\": \"<string>\",\n  \"competitors\": [\n    \"<string>\"\n  ],\n  \"url\": \"<string>\",\n  \"country\": \"<string>\",\n  \"limit\": 50,\n  \"task_id\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "id": "<string>",
  "run_url": "<string>",
  "provider": "<string>",
  "endpoint": "<string>",
  "endpoint_version": 123,
  "status": "QUEUED",
  "failure": {
    "kind": "TIMED_OUT",
    "message": "<string>"
  },
  "input": {},
  "output": {
    "items": [
      {
        "keyword": "<string>",
        "volume": 123,
        "cpc_usd": 123,
        "semrush_keyword_difficulty": 123,
        "serpstat_keyword_difficulty": 123,
        "dataforseo_keyword_difficulty": 123,
        "ahrefs_keyword_difficulty": 123,
        "intent": "<string>"
      }
    ]
  },
  "provider_response": {
    "http_status": 349,
    "error": null
  },
  "charge_usd": "<string>",
  "charge_basis": {
    "clause": "rule",
    "quantity": 1
  },
  "stoppable": true,
  "stop_requested_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "task_id": "<string>",
  "metadata": {},
  "action": "keyword_overview",
  "result_status": "success",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "runs": [
    {
      "id": "<string>",
      "run_url": "<string>",
      "provider": "<string>",
      "endpoint": "<string>",
      "endpoint_version": 123,
      "status": "QUEUED",
      "failure": {
        "kind": "TIMED_OUT",
        "message": "<string>"
      },
      "input": {
        "omitted": true
      },
      "output": {
        "omitted": true
      },
      "provider_response": {
        "http_status": 349
      },
      "charge_usd": "<string>",
      "charge_basis": {
        "clause": "rule",
        "quantity": 1
      },
      "stoppable": true,
      "stop_requested_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "task_id": "<string>",
      "metadata": {}
    }
  ],
  "result_url": "<string>"
}

{
  "id": "<string>",
  "run_url": "<string>",
  "provider": "<string>",
  "endpoint": "<string>",
  "endpoint_version": 123,
  "status": "QUEUED",
  "failure": {
    "kind": "TIMED_OUT",
    "message": "<string>"
  },
  "input": {},
  "output": {
    "items": [
      {
        "keyword": "<string>",
        "volume": 123,
        "cpc_usd": 123,
        "semrush_keyword_difficulty": 123,
        "serpstat_keyword_difficulty": 123,
        "dataforseo_keyword_difficulty": 123,
        "ahrefs_keyword_difficulty": 123,
        "intent": "<string>"
      }
    ]
  },
  "provider_response": {
    "http_status": 349,
    "error": null
  },
  "charge_usd": "<string>",
  "charge_basis": {
    "clause": "rule",
    "quantity": 1
  },
  "stoppable": true,
  "stop_requested_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "task_id": "<string>",
  "metadata": {},
  "action": "keyword_overview",
  "result_status": "success",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "runs": [
    {
      "id": "<string>",
      "run_url": "<string>",
      "provider": "<string>",
      "endpoint": "<string>",
      "endpoint_version": 123,
      "status": "QUEUED",
      "failure": {
        "kind": "TIMED_OUT",
        "message": "<string>"
      },
      "input": {
        "omitted": true
      },
      "output": {
        "omitted": true
      },
      "provider_response": {
        "http_status": 349
      },
      "charge_usd": "<string>",
      "charge_basis": {
        "clause": "rule",
        "quantity": 1
      },
      "stoppable": true,
      "stop_requested_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "task_id": "<string>",
      "metadata": {}
    }
  ],
  "result_url": "<string>"
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "endpoint_not_permitted",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "rate_limited",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "service_unavailable",
    "message": "<string>",
    "reason": "<string>",
    "control": "<string>",
    "retry_after_ms": 123,
    "details": {}
  },
  "request_id": "<string>"
}

Cada ação retorna output normalizado. A saída nativa do Provedor não é repetida ali; ela permanece no Run e pode ser lida com Get Run. As ações de listagem expõem output.items[] com campos fixos por linha; as ações de visão geral expõem campos fixos no nível superior. Um valor que o Provedor selecionado não informa é null; o Glasser não converte nem preenche valores. Os valores monetários são sempre em USD (cpc_usd, organic_traffic_value_usd). volume, traffic e cpc_usd são estimativas próprias do Provedor que responde. Compare-os somente dentro de um mesmo Provedor (runs[].provider), não entre Provedores. Leia result_status separadamente de status: success, no_result, error ou pending. Uma resposta vazia, mas válida, é no_result e mantém o formato da ação: items é [], ou todos os campos de nível superior são null. error com error.code significa que a saída do Provedor não pôde ser entregue. charge_usd totaliza os runs desta resposta, incluindo resultados vazios cobrados, e é nulo até que todos os Runs sejam concluídos. Com provider: auto, o fallback pode criar vários Runs, cada um listado em runs[] com sua própria cobrança. Para um rastreamento pendente (site_audit, HTTP 202), siga o result_url autenticado. Get Run continua sendo nativo e informa uma cobrança individual. Consulte Seleção de Provedor e cobranças.

Saída por ação

Cada campo está presente em todas as linhas; um valor que o Provedor não informa é null. Os campos seguem as convenções de campos: os valores monetários terminam em _usd, os registros de data e hora terminam em _at (UTC ISO 8601), e domain é um nome de host simples, sem www. nem porta. As pontuações de autoridade mantêm a métrica e o nome próprios de cada Provedor e nunca são convertidas: ahrefs_domain_rating (Domain Rating da Ahrefs, 0–100, pode ter casas decimais), semrush_authority_score (Authority Score da Semrush, 0–100), dataforseo_rank (classificação da DataForSEO, 0–1000) e serpstat_domain_rank (Domain Rank da Serpstat, 0–100). A dificuldade de palavras-chave é dividida da mesma forma: semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty e ahrefs_keyword_difficulty são cada uma de 0–100 no modelo próprio do Provedor; portanto, a mesma palavra-chave pode receber pontuações muito diferentes entre eles. dataforseo_onpage_score é a pontuação própria de página da DataForSEO. Somente o campo do Provedor que respondeu é preenchido; os demais são null. position é a posição orgânica: 1 é o primeiro resultado orgânico, e recursos da SERP, como anúncios ou caixas de resposta, não são contabilizados.

`action`	`output`
`keyword_overview`	`items[]`: `keyword`, `volume`, `cpc_usd`, `semrush_keyword_difficulty`, `serpstat_keyword_difficulty`, `dataforseo_keyword_difficulty`, `ahrefs_keyword_difficulty`, `intent` (uma linha por `keyword`)
`keyword_ideas`	`items[]`: mesma linha que `keyword_overview`
`serp`	`items[]`: `position`, `url`, `domain`, `title`, `snippet` (`results` orgânico somente)
`domain_overview`	`organic_keywords`, `organic_traffic`, `organic_traffic_value_usd`, `paid_keywords`, `paid_traffic`
`ranked_keywords`	`items[]`: `keyword`, `position`, `url`, `volume`, `cpc_usd`, `traffic`
`organic_competitors`	`items[]`: `domain`, `common_keywords`, `organic_keywords` (`total` do concorrente), `organic_traffic`. O `domain` de destino e seus subdomínios são excluídos.
`backlinks_overview`	`backlinks`, `referring_domains`, `semrush_authority_score`, `dataforseo_rank`, `serpstat_domain_rank`, `dofollow_backlinks`, `nofollow_backlinks`
`backlinks`	`items[]`: `source_url`, `target_url`, `anchor`, `source_ahrefs_domain_rating`, `source_semrush_authority_score`, `source_dataforseo_rank`, `dofollow`, `first_seen_at`. Uma linha por link de cada Provedor.
`referring_domains`	`items[]`: `domain`, `ahrefs_domain_rating`, `semrush_authority_score`, `dataforseo_rank`, `backlinks`, `dofollow_backlinks`, `first_seen_at`
`domain_rating`	`ahrefs_domain_rating`
`site_audit`	`dataforseo_task_id` (`input` para os Endpoints do relatório OnPage da DataForSEO), `crawl_progress`, `crawl_stop_reason` (vocabulário da DataForSEO), `pages_crawled`, `dataforseo_onpage_score`, `broken_links`, `non_indexable`, `duplicate_title`, `duplicate_description`, `duplicate_content`
`keyword_gap`	`items[]`: `keyword`, `volume`, `cpc_usd`, `semrush_keyword_difficulty`, `dataforseo_keyword_difficulty`, `positions` `{domain: position}` (`null` = não está entre os 100 primeiros), indexados pelos domínios enviados por você
`backlink_gap`	`items[]`: `domain`, `dataforseo_rank`, `backlinks_per_target` `{competitor domain: count}`
`page_audit`	`url`, `status_code`, `title`, `description`, `canonical`, `dataforseo_onpage_score`, `internal_links`, `external_links`
`visibility_history`	`items[]`: `month`, `organic_keywords`, `organic_traffic`, `organic_traffic_value_usd`, `paid_keywords`, `paid_traffic`
`ai_citations`	`items[]`: `url`, `platform`, `mentions`, `ai_search_volume`, `is_target_domain`. Páginas mais citadas em respostas de IA que mencionam o `domain`, de qualquer site.
`ai_visibility`	`ahrefs_ai_citations`, `ahrefs_ai_cited_pages`, `ahrefs_ai_citations_by_platform` `{platform: citations}`, `dataforseo_ai_mentions_by_platform` `{platform: mentions}`, `dataforseo_ai_search_volume_by_platform` `{platform: AI search volume}`

As linhas de keyword_gap diferem conforme o Provedor: a Semrush retorna palavras-chave para as quais qualquer um dos domínios aparece no ranking (uma união), enquanto a DataForSEO retorna palavras-chave para as quais o concorrente aparece no ranking e você não. ai_visibility informa duas métricas diferentes: a Ahrefs contabiliza citações das páginas do domínio em respostas de IA, enquanto a DataForSEO contabiliza menções do domínio por LLMs. Cada Provedor preenche somente seus próprios campos, e não há um total entre Provedores. O first_seen_at da Semrush não contém fuso horário (a Semrush não informa nenhum), portanto não possui o sufixo Z.

{
  "action": "ranked_keywords",
  "provider": "dataforseo",
  "status": "COMPLETED",
  "result_status": "success",
  "output": {
    "items": [
      { "keyword": "zero interest business loan", "position": 1, "url": "https://stripe.com/resources/more/zero-interest-business-loans", "volume": 1600, "cpc_usd": 14.54, "traffic": 486.4 }
    ]
  },
  "charge_usd": "0.01236",
  "runs": [{ "provider": "dataforseo", "status": "COMPLETED", "charge_usd": "0.01236" }],
  "result_url": "/v1/solutions/gtm/seo_research/result?token=…"
}

Cabeçalhos

idempotency-key

string

obrigatório

Gere um valor exclusivo para cada execução pretendida (recomenda-se um UUID). Tente novamente com a mesma chave e os mesmos parâmetros de execução para recuperar o Run original sem uma segunda cobrança. Alterar os parâmetros de execução com a mesma chave retorna 409; alterar task_id ou metadata não atualiza o Run original.

Minimum string length: 1

Corpo

application/json

use_case

string | null

Uma breve descrição desta tarefa de SEO, incluindo seu assunto. Com task_id, salva a descrição do Task para revisar os resultados e avaliar se atendem à solicitação. Inclua apenas informações relevantes para esta tarefa, não o histórico da conversa nem detalhes pessoais não relacionados. Omita em chamadas posteriores para manter a descrição salva.

action

enum<string> | null

Padrão: keyword_overview.

keyword_overview: forneça uma ou mais palavras-chave.
keyword_ideas ou serp: forneça exatamente uma palavra-chave em keywords.
site_audit: forneça o domínio; limit é o número de páginas a rastrear (padrão 20, no máximo 100). O rastreamento é executado de forma assíncrona.
keyword_gap e backlink_gap: forneça o domínio e de um a quatro concorrentes.
page_audit: forneça url (uma página).
visibility_history: forneça o domínio; limit é o número de meses (padrão 12, no máximo 24).
Todas as outras ações: forneça o domínio. organic_competitors encontra domínios classificados para as mesmas palavras-chave; ai_visibility: visibilidade nas respostas de IA na métrica própria do provedor de dados que responde (Ahrefs: citações das páginas do domínio; DataForSEO: menções do domínio por LLM); ai_citations: páginas mais citadas em respostas de IA que mencionam o domínio, de qualquer site.
As linhas de keyword_gap variam conforme o provedor de dados: o Semrush retorna palavras-chave para as quais qualquer um dos domínios está classificado (união); o DataForSEO retorna palavras-chave para as quais o concorrente está classificado e você não está.

Opções disponíveis:

keyword_overview,

keyword_ideas,

serp,

domain_overview,

ranked_keywords,

organic_competitors,

backlinks_overview,

backlinks,

referring_domains,

domain_rating,

site_audit,

ai_visibility,

keyword_gap,

backlink_gap,

page_audit,

visibility_history,

ai_citations

provider

enum<string> | null

Padrão auto: seleciona o primeiro provedor de dados elegível na ordem de preferência da Glasser. Um provedor de dados nomeado deve aceitar a solicitação e ser permitido pela sua Key; não há fallback para outro provedor de dados. Os valores disponíveis estão listados abaixo.

Opções disponíveis:

auto,

semrush,

serpstat,

dataforseo,

ahrefs,

serper

keywords

string[] | null

Required array length: 1 - 20 elements

Required string length: 1 - 200

domain

string | null

Um domínio de site, como stripe.com. Uma URL completa é aceita e reduzida ao host.

Required string length: 3 - 253

competitors

string[] | null

Domínios concorrentes para keyword_gap e backlink_gap, de um a quatro. URLs completas são reduzidas ao host.

Required array length: 1 - 4 elements

Um domínio de site, como stripe.com. Uma URL completa é aceita e reduzida ao host.

Required string length: 3 - 253

url

string | null

Uma URL de página para page_audit, como https://stripe.com/pricing.

Required string length: 1 - 2048

country

string | null

País como código ISO de duas letras ou nome do país, por exemplo, us, gb, de, Germany. Padrão us. Códigos de país compatíveis: us, gb, ca, au, nz, ie, in, sg, de, at, ch, fr, be, es, mx, ar, it, nl, pt, br, jp, kr, cn, hk, tw, ru, pl, se, no, dk, fi, tr, id, th, vn, ph, my, za, ae, il, sa, eg, ng, ua, cz, gr, hu, ro, co, cl, pe, lu. A disponibilidade também depende da ação e do provedor de dados. Um país não compatível é recusado antes da criação de um Run. Não altere o país para contornar um erro; isso altera os dados solicitados.

Required string length: 2 - 60

limit

integer | null

Linhas a retornar. Mantenha um número pequeno: a regra de cobrança do endpoint roteado pode ler esse valor. Cada capacidade pode limitá-lo ainda mais.

Intervalo obrigatório: 1 <= x <= 100

task_id

string | null

Agrupe Runs relacionados, incluindo o fallback automático, em um único Task. Reutilize uma string estável e filtre a lista de Runs por task para recuperá-los.

metadata

Campos opcionais de acompanhamento, retornados no Run e disponíveis como filtros. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência.

Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres.
Valores: strings de 1–500 caracteres.
user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.

Entradas inválidas são descartadas por inteiro, não truncadas. A solicitação continua, e o Run retorna os campos que foram armazenados.

Show child attributes

Resposta

Success

string

obrigatório

run_url

string

obrigatório

Abra este Run no console. Requer associação ao Workspace.

provider

string

obrigatório

Pattern: ^[a-z0-9][a-z0-9-]*$

endpoint

string

obrigatório

Pattern: ^\/.+$

endpoint_version

integer

obrigatório

status

enum<string>

obrigatório

QUEUED ou RUNNING: ainda em andamento. COMPLETED: uma resposta do provedor de dados está disponível, incluindo respostas não 2xx. FAILED: consulte failure. STOPPED: interrompido antes do dispatch. Leia charge_usd separadamente de status.

Opções disponíveis:

QUEUED,

RUNNING,

COMPLETED,

FAILED,

STOPPED

failure

object | null

obrigatório

Motivo da falha do Run. Não nulo somente quando o status for FAILED.

Show child attributes

input

object

obrigatório

output

object

obrigatório

Campos normalizados por ação. A saída nativa do provedor de dados não é repetida aqui; ela permanece no Run (GET /v1/runs/:id). Os valores que um provedor de dados não informar serão nulos. Valores monetários estão em USD. As pontuações de autoridade mantêm a métrica e o nome próprios do provedor de dados que respondeu e nunca são convertidas: ahrefs_domain_rating (Ahrefs Domain Rating, 0–100), semrush_authority_score (Semrush Authority Score, 0–100), dataforseo_rank (classificação da DataForSEO, 0–1000), serpstat_domain_rank (Serpstat Domain Rank, 0–100). A dificuldade de palavras-chave é dividida da mesma forma (semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, cada uma de 0–100 em seu próprio modelo). Somente o campo do provedor de dados que respondeu é preenchido; os demais são nulos. volume, traffic e cpc são estimativas do provedor de dados que respondeu; compare-as somente dentro de um mesmo provedor de dados (runs[].provider). Uma resposta vazia (result_status no_result) mantém o formato da ação: items é [], ou todos os campos são nulos.

keyword_overview: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent
keyword_ideas: items[]: mesma linha de keyword_overview
serp: items[]: position (posição orgânica: 1 = primeiro resultado orgânico; recursos da SERP não são contabilizados), url, domain, title, snippet (somente resultados orgânicos)
domain_overview: organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic
ranked_keywords: items[]: keyword, position (posição orgânica: 1 = primeiro resultado orgânico; recursos da SERP não são contabilizados), url, volume, cpc_usd, traffic
organic_competitors: items[]: domain, common_keywords, organic_keywords (total do concorrente), organic_traffic (o domínio-alvo e seus subdomínios são excluídos)
backlinks_overview: backlinks, referring_domains, semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks, nofollow_backlinks
backlinks: items[]: source_url, target_url, anchor, source_ahrefs_domain_rating, source_semrush_authority_score, source_dataforseo_rank, dofollow, first_seen_at (ISO 8601 UTC; Semrush: fuso não informado, sem sufixo Z). Uma linha por link de cada provedor de dados
referring_domains: items[]: domain, ahrefs_domain_rating, semrush_authority_score, dataforseo_rank, backlinks, dofollow_backlinks, first_seen_at (ISO 8601 UTC; Semrush: fuso não informado, sem sufixo Z)
domain_rating: ahrefs_domain_rating
site_audit: dataforseo_task_id (entrada para os endpoints de relatório OnPage da DataForSEO), crawl_progress, crawl_stop_reason (vocabulário da DataForSEO), pages_crawled, dataforseo_onpage_score, broken_links, non_indexable, duplicate_title, duplicate_description, duplicate_content
keyword_gap: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, dataforseo_keyword_difficulty, positions {domain: posição orgânica; null = não está entre os 100 primeiros}, indexado pelos domínios enviados. As linhas da Semrush são palavras-chave para as quais qualquer um dos domínios está classificado (união); as linhas da DataForSEO são palavras-chave para as quais o concorrente está classificado e você não
backlink_gap: items[]: domain, dataforseo_rank, backlinks_per_target {domínio concorrente: contagem}
page_audit: url, status_code, title, description, canonical, dataforseo_onpage_score, internal_links, external_links
visibility_history: items[]: month, organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic
ai_citations: items[]: url, platform, mentions, ai_search_volume, is_target_domain (páginas mais citadas em respostas de IA que mencionam o domínio, de qualquer site)
ai_visibility: ahrefs_ai_citations, ahrefs_ai_cited_pages, ahrefs_ai_citations_by_platform {platform: citations}, dataforseo_ai_mentions_by_platform {platform: mentions}, dataforseo_ai_search_volume_by_platform {platform: volume de pesquisa de IA}. Cada provedor de dados preenche somente seus próprios campos; não há total entre provedores

Show child attributes

provider_response

object | null

obrigatório

Não nulo somente quando o status for COMPLETED.

Para respostas 2xx, output contém o JSON nativo do provedor de dados (qualquer formato) ou null para um corpo vazio.
Para respostas não 2xx, error contém o corpo de erro do provedor de dados e output é null.

Os campos confidenciais são removidos de ambos os corpos.

Show child attributes

charge_usd

string | null

obrigatório

Cobrança total dos Runs nesta resposta de Solution. Nulo até que todos os Runs listados sejam finalizados. Cada Run mantém sua própria cobrança; falhas também podem ser cobradas.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$

charge_basis

object | null

obrigatório

Base de cobrança de um único Run ou nulo para um total de vários Runs. Leia runs[].charge_basis para cada cobrança.

Show child attributes

stoppable

boolean

obrigatório

Indica se uma solicitação de parada pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do dispatch.

stop_requested_at

string<date-time> | null

obrigatório

Quando uma parada foi solicitada. O Run ainda pode continuar se o dispatch já tiver começado.

created_at

string<date-time>

obrigatório

Timestamp UTC no formato ISO-8601

started_at

string<date-time> | null

obrigatório

Timestamp UTC no formato ISO-8601

completed_at

string<date-time> | null

obrigatório

Timestamp UTC no formato ISO-8601

task_id

string | null

obrigatório

metadata

object

obrigatório

Seus campos de rastreamento armazenados. Use-os para filtrar Runs. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência.

Até 20 chaves: letras minúsculas, dígitos e sublinhados; devem começar com uma letra; no máximo 40 caracteres.
Valores: strings de 1 a 500 caracteres.
user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.

Show child attributes

action

enum<string>

obrigatório

Opções disponíveis:

keyword_overview,

keyword_ideas,

serp,

domain_overview,

ranked_keywords,

organic_competitors,

backlinks_overview,

backlinks,

referring_domains,

domain_rating,

site_audit,

ai_visibility,

keyword_gap,

backlink_gap,

page_audit,

visibility_history,

ai_citations

result_status

enum<string>

obrigatório

Status de entrega comercial, independente do ciclo de vida final do Run em status. no_result é uma resposta vazia, mas válida; error significa que não foi possível entregar a saída do provedor de dados.

Opções disponíveis:

success,

no_result,

error,

pending

error

object | null

obrigatório

Show child attributes

runs

object[]

obrigatório

Show child attributes

result_url

string

obrigatório

Caminho de URL autenticado e somente leitura para consultar este resultado normalizado e a cobrança total. Use-o com a origem da API. Não cria Runs nem retoma o fallback. GET /v1/runs/:id ainda retorna o Run individual nativo.

Primeiros passos

Endpoints

Run

Saldo

Fontes de dados

Solutions

Pesquisa de SEO

Saída por ação

Cabeçalhos

Corpo

Resposta

​Saída por ação

Cabeçalhos

Corpo

Resposta

Saída por ação