{
  "url": "https://telipot.com/catalog/tasks/google-search-console.search.analytics",
  "id": "google-search-console.search.analytics",
  "name": "Search queries, clicks and impressions for a verified site",
  "provider": {
    "slug": "google-search-console",
    "name": "Google Search Console"
  },
  "capability": "search-console.queries",
  "platform": "search-console",
  "kind": "data",
  "tier": "core",
  "identity": "account",
  "identityLabel": "Company account",
  "price": {
    "amount": "Free",
    "state": "free",
    "label": "Free",
    "detail": "Free from the tool",
    "type": "free"
  },
  "providers": 1,
  "retention": "standard",
  "runsOn": "free",
  "live": true,
  "summary": "Query your data with filters and parameters that you define. Returns zero or more rows grouped by the row keys that you define. You must define a date range of one or more days. When date is one of the group by values, any days without data are omitted from the result list. If you need to know which days have data, issue a broad date range query grouped by date for any metric, and see which day rows are returned.",
  "method": "POST",
  "path": "/webmasters/v3/sites/{siteUrl}/searchAnalytics/query",
  "host": "https://searchconsole.googleapis.com",
  "docsUrl": "https://developers.google.com/webmaster-tools/v1/searchanalytics/query",
  "auth": {
    "scheme": "oauth",
    "label": "oauth · OAuth 2.0 with PKCE",
    "short": "oauth · OAuth 2.0"
  },
  "scope": "own_account",
  "principal": "organization",
  "requiredScopes": [
    "webmasters.readonly"
  ],
  "verification": {
    "state": "none",
    "label": "Not verified yet",
    "detail": "Not checked yet. We test with a real request before we mark it."
  },
  "input": [
    {
      "name": "siteUrl",
      "location": "pathParams",
      "type": "string",
      "required": true,
      "constraints": [],
      "note": "The property as sites.list returns it, a URL-prefix property with its trailing slash or a domain property written sc-domain:example.com"
    },
    {
      "name": "startDate",
      "location": "body",
      "type": "string",
      "required": true,
      "constraints": [],
      "note": "YYYY-MM-DD in Pacific time, included in the range"
    },
    {
      "name": "endDate",
      "location": "body",
      "type": "string",
      "required": true,
      "constraints": [],
      "note": "YYYY-MM-DD in Pacific time, included in the range"
    },
    {
      "name": "dimensions",
      "location": "body",
      "type": "array",
      "required": false,
      "constraints": [],
      "note": "Zero or more of country, device, page, query, searchAppearance, date and hour, grouped in this order. With none, every value is combined into one row. Grouping by hour needs dataState hourly_all."
    },
    {
      "name": "type",
      "location": "body",
      "type": "string",
      "required": false,
      "constraints": [
        "one of \"web\", \"image\", \"video\", \"news\", \"discover\", \"googleNews\"",
        "default \"web\""
      ],
      "note": "The search type to report on; web is the combined All tab and leaves out Discover and Google News"
    },
    {
      "name": "dimensionFilterGroups",
      "location": "body",
      "type": "array",
      "required": false,
      "constraints": [],
      "note": "Groups that must all match for a row to be returned. A group is a groupType of and and its filters, each a dimension (country, device, page, query or searchAppearance), an operator (equals, notEquals, contains, notContains, includingRegex or excludingRegex) and an expression."
    },
    {
      "name": "aggregationType",
      "location": "body",
      "type": "string",
      "required": false,
      "constraints": [
        "one of \"auto\", \"byPage\", \"byProperty\", \"byNewsShowcasePanel\"",
        "default \"auto\""
      ],
      "note": "How data is aggregated; grouping or filtering by page rules out byProperty"
    },
    {
      "name": "rowLimit",
      "location": "body",
      "type": "integer",
      "required": false,
      "constraints": [
        "1 to 25000",
        "default 1000"
      ],
      "note": "Rows to return; page through the rest with startRow"
    },
    {
      "name": "startRow",
      "location": "body",
      "type": "integer",
      "required": false,
      "constraints": [
        "at least 0",
        "default 0"
      ],
      "note": "Zero-based index of the first row"
    },
    {
      "name": "dataState",
      "location": "body",
      "type": "string",
      "required": false,
      "constraints": [
        "one of \"final\", \"all\", \"hourly_all\"",
        "default \"final\""
      ],
      "note": "all adds fresh data that is still partial; hourly_all adds the hourly breakdown"
    }
  ],
  "sampleInput": {
    "siteUrl": "sc-domain:example.com",
    "startDate": "2026-09-01",
    "endDate": "2026-09-30"
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "siteUrl": {
        "type": "string",
        "description": "The property as sites.list returns it, a URL-prefix property with its trailing slash or a domain property written sc-domain:example.com",
        "examples": [
          "sc-domain:example.com"
        ]
      },
      "startDate": {
        "type": "string",
        "description": "YYYY-MM-DD in Pacific time, included in the range",
        "examples": [
          "2026-09-01"
        ]
      },
      "endDate": {
        "type": "string",
        "description": "YYYY-MM-DD in Pacific time, included in the range",
        "examples": [
          "2026-09-30"
        ]
      },
      "dimensions": {
        "type": "array",
        "description": "Zero or more of country, device, page, query, searchAppearance, date and hour, grouped in this order. With none, every value is combined into one row. Grouping by hour needs dataState hourly_all.",
        "examples": [
          [
            "query"
          ]
        ]
      },
      "type": {
        "type": "string",
        "description": "The search type to report on; web is the combined All tab and leaves out Discover and Google News",
        "enum": [
          "web",
          "image",
          "video",
          "news",
          "discover",
          "googleNews"
        ],
        "default": "web"
      },
      "dimensionFilterGroups": {
        "type": "array",
        "description": "Groups that must all match for a row to be returned. A group is a groupType of and and its filters, each a dimension (country, device, page, query or searchAppearance), an operator (equals, notEquals, contains, notContains, includingRegex or excludingRegex) and an expression.",
        "examples": [
          [
            {
              "groupType": "and",
              "filters": [
                {
                  "dimension": "query",
                  "operator": "contains",
                  "expression": "agent"
                }
              ]
            }
          ]
        ]
      },
      "aggregationType": {
        "type": "string",
        "description": "How data is aggregated; grouping or filtering by page rules out byProperty",
        "enum": [
          "auto",
          "byPage",
          "byProperty",
          "byNewsShowcasePanel"
        ],
        "default": "auto"
      },
      "rowLimit": {
        "type": "integer",
        "description": "Rows to return; page through the rest with startRow",
        "default": 1000,
        "minimum": 1,
        "maximum": 25000
      },
      "startRow": {
        "type": "integer",
        "description": "Zero-based index of the first row",
        "default": 0,
        "minimum": 0
      },
      "dataState": {
        "type": "string",
        "description": "all adds fresh data that is still partial; hourly_all adds the hourly breakdown",
        "enum": [
          "final",
          "all",
          "hourly_all"
        ],
        "default": "final"
      }
    },
    "required": [
      "siteUrl",
      "startDate",
      "endDate"
    ],
    "additionalProperties": false
  },
  "output": [
    {
      "name": "rows",
      "type": "object[]",
      "description": "Sorted by clicks, descending, or by date, ascending, when grouped by date. Absent when no row matches."
    },
    {
      "name": "responseAggregationType",
      "type": "string",
      "description": "How the results were aggregated"
    },
    {
      "name": "metadata",
      "type": "object",
      "description": "Present when the request asked for fresh or hourly data"
    }
  ],
  "outputSchema": {
    "type": "object",
    "properties": {
      "rows": {
        "type": "array",
        "description": "Sorted by clicks, descending, or by date, ascending, when grouped by date. Absent when no row matches.",
        "items": {
          "type": "object",
          "required": [
            "clicks",
            "impressions",
            "ctr",
            "position"
          ],
          "properties": {
            "keys": {
              "type": "array",
              "description": "The dimension values of the row, in the order the request grouped by them; absent when no dimensions are requested",
              "items": {
                "type": "string"
              }
            },
            "clicks": {
              "type": "number"
            },
            "impressions": {
              "type": "number"
            },
            "ctr": {
              "type": "number",
              "description": "From 0 to 1"
            },
            "position": {
              "type": "number",
              "description": "Average position in search results"
            }
          }
        }
      },
      "responseAggregationType": {
        "type": "string",
        "description": "How the results were aggregated"
      },
      "metadata": {
        "type": "object",
        "description": "Present when the request asked for fresh or hourly data",
        "properties": {
          "firstIncompleteDate": {
            "type": "string"
          },
          "firstIncompleteHour": {
            "type": "string"
          }
        }
      }
    }
  },
  "example": {
    "file": "examples/google-search-console.search.analytics.json",
    "json": {
      "rows": [
        {
          "keys": [
            "agent tools"
          ],
          "clicks": 128,
          "impressions": 4210,
          "ctr": 0.0304,
          "position": 6.4
        },
        {
          "keys": [
            "tool gateway for agents"
          ],
          "clicks": 41,
          "impressions": 1388,
          "ctr": 0.0295,
          "position": 8.1
        }
      ],
      "responseAggregationType": "byProperty"
    }
  },
  "commands": {
    "mode": "run",
    "cli": "telipot run google-search-console.search.analytics \\\n  --input-json '{\"siteUrl\":\"sc-domain:example.com\",\"startDate\":\"2026-09-01\",\"endDate\":\"2026-09-30\"}'",
    "http": "curl https://api.telipot.com/v1/tasks/google-search-console.search.analytics/run \\\n  -H \"Authorization: Bearer $TELIPOT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"siteUrl\":\"sc-domain:example.com\",\"startDate\":\"2026-09-01\",\"endDate\":\"2026-09-30\"}'",
    "quote": "telipot run google-search-console.search.analytics \\\n  --input-json '{\"siteUrl\":\"sc-domain:example.com\",\"startDate\":\"2026-09-01\",\"endDate\":\"2026-09-30\"}' \\\n  --quote"
  },
  "siblings": []
}