{
  "url": "https://telipot.com/catalog/tasks/google-analytics.reports.run",
  "id": "google-analytics.reports.run",
  "name": "Metrics by dimension and date range for a property",
  "provider": {
    "slug": "google-analytics",
    "name": "Google Analytics 4"
  },
  "capability": "analytics.reports.run",
  "platform": "analytics",
  "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": "Returns a customized report of your Google Analytics event data. Reports contain statistics derived from data collected by the Google Analytics tracking code. The data returned from the API is as a table with columns for the requested dimensions and metrics. Metrics are individual measurements of user activity on your property, such as active users or event count. Dimensions break down metrics across some common criteria, such as country or event name.",
  "method": "POST",
  "path": "/v1beta/properties/{propertyId}:runReport",
  "host": "https://analyticsdata.googleapis.com",
  "docsUrl": "https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport",
  "auth": {
    "scheme": "oauth",
    "label": "oauth · OAuth 2.0 with PKCE",
    "short": "oauth · OAuth 2.0"
  },
  "scope": "own_account",
  "principal": "organization",
  "requiredScopes": [
    "analytics.readonly"
  ],
  "verification": {
    "state": "none",
    "label": "Not verified yet",
    "detail": "Not checked yet. We test with a real request before we mark it."
  },
  "input": [
    {
      "name": "propertyId",
      "location": "pathParams",
      "type": "string",
      "required": true,
      "constraints": [],
      "note": "The numeric id of a GA4 property, as google-analytics.accounts.summaries returns it after properties/"
    },
    {
      "name": "dateRanges",
      "location": "body",
      "type": "array",
      "required": true,
      "constraints": [],
      "note": "Up to 4 ranges, each a startDate and an endDate, either YYYY-MM-DD or NdaysAgo, yesterday or today. With several, each row carries the index of its range."
    },
    {
      "name": "dimensions",
      "location": "body",
      "type": "array",
      "required": false,
      "constraints": [],
      "note": "Up to 9 dimensions, each an object with the name of one the property offers, such as country or eventName; google-analytics.properties.metadata lists them"
    },
    {
      "name": "metrics",
      "location": "body",
      "type": "array",
      "required": true,
      "constraints": [],
      "note": "Up to 10 metrics, each an object with the name of one the property offers, such as activeUsers or eventCount; google-analytics.properties.metadata lists them"
    },
    {
      "name": "dimensionFilter",
      "location": "body",
      "type": "object",
      "required": false,
      "constraints": [],
      "note": "A filter expression over dimensions, applied before the metrics are aggregated"
    },
    {
      "name": "metricFilter",
      "location": "body",
      "type": "object",
      "required": false,
      "constraints": [],
      "note": "A filter expression over metrics, applied after the rows are aggregated, as a SQL HAVING clause is"
    },
    {
      "name": "orderBys",
      "location": "body",
      "type": "array",
      "required": false,
      "constraints": [],
      "note": "How the rows are ordered, each an order by a dimension or a metric"
    },
    {
      "name": "limit",
      "location": "body",
      "type": "integer",
      "required": false,
      "constraints": [
        "1 to 250000",
        "default 10000"
      ],
      "note": "Rows to return; a report can return fewer"
    },
    {
      "name": "offset",
      "location": "body",
      "type": "integer",
      "required": false,
      "constraints": [
        "at least 0",
        "default 0"
      ],
      "note": "Zero-based index of the first row, for paging"
    },
    {
      "name": "metricAggregations",
      "location": "body",
      "type": "array",
      "required": false,
      "constraints": [],
      "note": "TOTAL, MINIMUM or MAXIMUM, each adding a row of that aggregate of every metric"
    },
    {
      "name": "currencyCode",
      "location": "body",
      "type": "string",
      "required": false,
      "constraints": [],
      "note": "An ISO 4217 code for currency metrics; the property's own currency when absent"
    },
    {
      "name": "keepEmptyRows",
      "location": "body",
      "type": "boolean",
      "required": false,
      "constraints": [
        "default false"
      ],
      "note": "Whether to return rows whose metrics are all 0"
    },
    {
      "name": "returnPropertyQuota",
      "location": "body",
      "type": "boolean",
      "required": false,
      "constraints": [
        "default false"
      ],
      "note": "Whether to add the property's quota state to the answer"
    }
  ],
  "sampleInput": {
    "propertyId": "123456789",
    "dateRanges": [
      {
        "startDate": "2026-09-01",
        "endDate": "2026-09-30"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "propertyId": {
        "type": "string",
        "description": "The numeric id of a GA4 property, as google-analytics.accounts.summaries returns it after properties/",
        "examples": [
          "123456789"
        ]
      },
      "dateRanges": {
        "type": "array",
        "description": "Up to 4 ranges, each a startDate and an endDate, either YYYY-MM-DD or NdaysAgo, yesterday or today. With several, each row carries the index of its range.",
        "examples": [
          [
            {
              "startDate": "2026-09-01",
              "endDate": "2026-09-30"
            }
          ]
        ]
      },
      "dimensions": {
        "type": "array",
        "description": "Up to 9 dimensions, each an object with the name of one the property offers, such as country or eventName; google-analytics.properties.metadata lists them",
        "examples": [
          [
            {
              "name": "country"
            }
          ]
        ]
      },
      "metrics": {
        "type": "array",
        "description": "Up to 10 metrics, each an object with the name of one the property offers, such as activeUsers or eventCount; google-analytics.properties.metadata lists them",
        "examples": [
          [
            {
              "name": "activeUsers"
            }
          ]
        ]
      },
      "dimensionFilter": {
        "type": "object",
        "description": "A filter expression over dimensions, applied before the metrics are aggregated",
        "examples": [
          {
            "filter": {
              "fieldName": "country",
              "stringFilter": {
                "matchType": "EXACT",
                "value": "Germany"
              }
            }
          }
        ]
      },
      "metricFilter": {
        "type": "object",
        "description": "A filter expression over metrics, applied after the rows are aggregated, as a SQL HAVING clause is"
      },
      "orderBys": {
        "type": "array",
        "description": "How the rows are ordered, each an order by a dimension or a metric",
        "examples": [
          [
            {
              "metric": {
                "metricName": "activeUsers"
              },
              "desc": true
            }
          ]
        ]
      },
      "limit": {
        "type": "integer",
        "description": "Rows to return; a report can return fewer",
        "default": 10000,
        "minimum": 1,
        "maximum": 250000
      },
      "offset": {
        "type": "integer",
        "description": "Zero-based index of the first row, for paging",
        "default": 0,
        "minimum": 0
      },
      "metricAggregations": {
        "type": "array",
        "description": "TOTAL, MINIMUM or MAXIMUM, each adding a row of that aggregate of every metric",
        "examples": [
          [
            "TOTAL"
          ]
        ]
      },
      "currencyCode": {
        "type": "string",
        "description": "An ISO 4217 code for currency metrics; the property's own currency when absent",
        "examples": [
          "USD"
        ]
      },
      "keepEmptyRows": {
        "type": "boolean",
        "description": "Whether to return rows whose metrics are all 0",
        "default": false
      },
      "returnPropertyQuota": {
        "type": "boolean",
        "description": "Whether to add the property's quota state to the answer",
        "default": false
      }
    },
    "required": [
      "propertyId",
      "dateRanges",
      "metrics"
    ],
    "additionalProperties": false
  },
  "output": [
    {
      "name": "dimensionHeaders",
      "type": "object[]"
    },
    {
      "name": "metricHeaders",
      "type": "object[]"
    },
    {
      "name": "rows",
      "type": "object[]",
      "description": "Absent when no row matches. Each row holds the values of the dimension and metric headers, in their order."
    },
    {
      "name": "totals",
      "type": "object[]",
      "description": "Present when metricAggregations asked for TOTAL"
    },
    {
      "name": "maximums",
      "type": "object[]",
      "description": "Present when metricAggregations asked for MAXIMUM"
    },
    {
      "name": "minimums",
      "type": "object[]",
      "description": "Present when metricAggregations asked for MINIMUM"
    },
    {
      "name": "rowCount",
      "type": "integer",
      "description": "Rows in the result before limit and offset"
    },
    {
      "name": "metadata",
      "type": "object"
    },
    {
      "name": "propertyQuota",
      "type": "object",
      "description": "Present when returnPropertyQuota is true; each quota holds consumed and remaining"
    },
    {
      "name": "kind",
      "type": "string"
    }
  ],
  "outputSchema": {
    "type": "object",
    "properties": {
      "dimensionHeaders": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      },
      "metricHeaders": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "description": "The kind of value such as TYPE_INTEGER or TYPE_CURRENCY"
            }
          }
        }
      },
      "rows": {
        "type": "array",
        "description": "Absent when no row matches. Each row holds the values of the dimension and metric headers, in their order.",
        "items": {
          "type": "object",
          "properties": {
            "dimensionValues": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "string"
                  }
                }
              }
            },
            "metricValues": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "string",
                    "description": "A number as a string"
                  }
                }
              }
            }
          }
        }
      },
      "totals": {
        "type": "array",
        "description": "Present when metricAggregations asked for TOTAL",
        "items": {
          "type": "object"
        }
      },
      "maximums": {
        "type": "array",
        "description": "Present when metricAggregations asked for MAXIMUM",
        "items": {
          "type": "object"
        }
      },
      "minimums": {
        "type": "array",
        "description": "Present when metricAggregations asked for MINIMUM",
        "items": {
          "type": "object"
        }
      },
      "rowCount": {
        "type": "integer",
        "description": "Rows in the result before limit and offset"
      },
      "metadata": {
        "type": "object",
        "properties": {
          "currencyCode": {
            "type": "string"
          },
          "timeZone": {
            "type": "string",
            "description": "The property's time zone"
          },
          "dataLossFromOtherRow": {
            "type": "boolean",
            "description": "True when some dimension combinations are rolled into an (other) row"
          },
          "subjectToThresholding": {
            "type": "boolean",
            "description": "True when the report leaves out data below a privacy threshold"
          },
          "emptyReason": {
            "type": "string"
          }
        }
      },
      "propertyQuota": {
        "type": "object",
        "description": "Present when returnPropertyQuota is true; each quota holds consumed and remaining"
      },
      "kind": {
        "type": "string"
      }
    }
  },
  "example": {
    "file": "examples/google-analytics.reports.run.json",
    "json": {
      "dimensionHeaders": [
        {
          "name": "country"
        }
      ],
      "metricHeaders": [
        {
          "name": "activeUsers",
          "type": "TYPE_INTEGER"
        }
      ],
      "rows": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ],
          "metricValues": [
            {
              "value": "1842"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Germany"
            }
          ],
          "metricValues": [
            {
              "value": "311"
            }
          ]
        }
      ],
      "rowCount": 37,
      "metadata": {
        "currencyCode": "USD",
        "timeZone": "America/Los_Angeles"
      },
      "kind": "analyticsData#runReport"
    }
  },
  "commands": {
    "mode": "run",
    "cli": "telipot run google-analytics.reports.run \\\n  --input-json '{\"propertyId\":\"123456789\",\"dateRanges\":[{\"startDate\":\"2026-09-01\",\"endDate\":\"2026-09-30\"}],\"metrics\":[{\"name\":\"activeUsers\"}]}'",
    "http": "curl https://api.telipot.com/v1/tasks/google-analytics.reports.run/run \\\n  -H \"Authorization: Bearer $TELIPOT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"propertyId\":\"123456789\",\"dateRanges\":[{\"startDate\":\"2026-09-01\",\"endDate\":\"2026-09-30\"}],\"metrics\":[{\"name\":\"activeUsers\"}]}'",
    "quote": "telipot run google-analytics.reports.run \\\n  --input-json '{\"propertyId\":\"123456789\",\"dateRanges\":[{\"startDate\":\"2026-09-01\",\"endDate\":\"2026-09-30\"}],\"metrics\":[{\"name\":\"activeUsers\"}]}' \\\n  --quote"
  },
  "siblings": []
}