Responses

This page describes REST API JSON responses.

GoodMetrics REST API responses are JSON. Successful responses include meta and data.

Realtime responses

Realtime endpoints return a timestamp window and an array of live rows.

{
  "meta": {
    "start": 1772476740000,
    "end": 1772476800000
  },
  "data": [
    {
      "activeSessions": 14
    }
  ]
}

The fields inside data depend on the realtime endpoint.

Chart responses

Chart responses return aligned arrays. Single-range requests include data in primary and empty secondary and change arrays.

{
  "meta": {
    "start": 1771872000000,
    "end": 1772476799000,
    "timezone": "America/Toronto",
    "interval": "day",
    "type": "unique_visitors",
    "total": {
      "primary": [1234],
      "secondary": [],
      "change": []
    }
  },
  "data": {
    "primary": [
      {
        "datetime": "2026-02-25",
        "count": 183
      }
    ],
    "secondary": [],
    "change": []
  }
}

Comparison requests include secondary rows and change objects with delta and percent.

Table responses

Table endpoints use a standard response structure.

{
  "meta": {
    "start": 1771872000000,
    "end": 1772476799000,
    "cursor": "cursor-value",
    "page": 0,
    "pageTotal": 4,
    "totalRecords": 37,
    "topFiveEntries": {
      "primary": [
        {
          "name": "Canada",
          "total": 620
        }
      ],
      "secondary": [],
      "change": []
    },
    "totals": {
      "primary": {
        "sessions": 1400,
        "uniqueVisitors": 1100
      },
      "secondary": {},
      "change": {}
    }
  },
  "data": {
    "primary": [
      {
        "country": "Canada",
        "sessions": 620,
        "uniqueVisitors": 510,
        "sessionsPercentage": 44.29
      }
    ],
    "secondary": [],
    "change": []
  }
}

Table row fields depend on the endpoint. Common fields include sessions, uniqueVisitors, newVisitors, pageViews, avgSessionLength, bounceRate, pagesPerSession, eventCompletions, eventValue, and eventConversionRate.

Comparison responses

When a request includes two date ranges:

• primary contains rows for the first range.
• secondary contains rows for the second range.
• change contains delta and percent values comparing primary against secondary.
• meta.secondaryStart and meta.secondaryEnd are included.

Error responses

Error responses include an errors array.

{
  "errors": ["Unauthorized request"]
}

Common statuses:

Status	Meaning
400	Invalid query parameters, validation failure, or report execution error.
401	Missing or invalid bearer token.
403	Token owner lacks required access, or a non-GET request was attempted.
404	Site GMID or route was not found.
429	Rate limit exceeded.