dev.cartridge.analytics.getGameAnalytics Documentation (EN)

main query

Owner-facing analytics for a single game. Authenticates the caller, verifies they own the game, then merges ClickHouse rollups with record-creation trends from HappyView. Fractional metrics use `unknown` because atproto lexicons have no float type.

Parameters

range string Optional

Reporting window ending today (UTC).

slug string Required

Slug of the game to report on. The caller must own it.

Output

Encodingapplication/json

attribution ref#attribution Required

No description available.

conversions ref#conversions Required

No description available.

discovery ref#discovery Required

No description available.

engagement ref#engagement Required

No description available.

generatedAt stringdatetime Required

An RFC 3339 formatted timestamp.

name string Required

No description available.

range string Required

No description available.

Known values: 7d, 30d, 90d

slug string Required

No description available.

totals ref#totals Required

No description available.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://api.bsky.social)

Parameters

range Reporting window ending today (UTC).

slug * Slug of the game to report on. The caller must own it.

View raw schema

{
  "type": "query",
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "slug",
        "name",
        "range",
        "generatedAt",
        "totals",
        "discovery",
        "attribution",
        "engagement",
        "conversions"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        },
        "range": {
          "type": "string",
          "knownValues": [
            "7d",
            "30d",
            "90d"
          ]
        },
        "totals": {
          "ref": "#totals",
          "type": "ref"
        },
        "discovery": {
          "ref": "#discovery",
          "type": "ref"
        },
        "engagement": {
          "ref": "#engagement",
          "type": "ref"
        },
        "attribution": {
          "ref": "#attribution",
          "type": "ref"
        },
        "conversions": {
          "ref": "#conversions",
          "type": "ref"
        },
        "generatedAt": {
          "type": "string",
          "format": "datetime"
        }
      }
    },
    "encoding": "application/json"
  },
  "parameters": {
    "type": "params",
    "required": [
      "slug"
    ],
    "properties": {
      "slug": {
        "type": "string",
        "maxLength": 512,
        "description": "Slug of the game to report on. The caller must own it."
      },
      "range": {
        "type": "string",
        "default": "30d",
        "description": "Reporting window ending today (UTC).",
        "knownValues": [
          "7d",
          "30d",
          "90d"
        ]
      }
    }
  },
  "description": "Owner-facing analytics for a single game. Authenticates the caller, verifies they own the game, then merges ClickHouse rollups with record-creation trends from HappyView. Fractional metrics use `unknown` because atproto lexicons have no float type."
}

attribution object

No description available.

Properties

ctrBySurface array of ref#ctrBySurface Required

No description available.

topReferrerFeeds array of ref#namedCount Required

No description available.

trafficSources array of ref#namedCount Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "trafficSources",
    "topReferrerFeeds",
    "ctrBySurface"
  ],
  "properties": {
    "ctrBySurface": {
      "type": "array",
      "items": {
        "ref": "#ctrBySurface",
        "type": "ref"
      }
    },
    "trafficSources": {
      "type": "array",
      "items": {
        "ref": "#namedCount",
        "type": "ref"
      }
    },
    "topReferrerFeeds": {
      "type": "array",
      "items": {
        "ref": "#namedCount",
        "type": "ref"
      }
    }
  }
}

conversions object

No description available.

Properties

funnel ref #funnel Required

No description available.

recordTrends array of ref#recordTrendPoint Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "recordTrends",
    "funnel"
  ],
  "properties": {
    "funnel": {
      "ref": "#funnel",
      "type": "ref"
    },
    "recordTrends": {
      "type": "array",
      "items": {
        "ref": "#recordTrendPoint",
        "type": "ref"
      }
    }
  }
}

ctrBySurface object

No description available.

Properties

clicks integer Required

No description available.

ctr unknown Required

clicks / impressions for this surface, 0..1 (float; unknown-typed).

impressions integer Required

No description available.

surface string Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "surface",
    "impressions",
    "clicks",
    "ctr"
  ],
  "properties": {
    "ctr": {
      "type": "unknown",
      "description": "clicks / impressions for this surface, 0..1 (float; unknown-typed)."
    },
    "clicks": {
      "type": "integer"
    },
    "surface": {
      "type": "string"
    },
    "impressions": {
      "type": "integer"
    }
  }
}

discovery object

No description available.

Properties

feedBreakdown array of ref#namedCount Required

No description available.

impressionsOverTime array of ref#impressionPoint Required

No description available.

topSearchTerms array of ref#namedCount Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "impressionsOverTime",
    "feedBreakdown",
    "topSearchTerms"
  ],
  "properties": {
    "feedBreakdown": {
      "type": "array",
      "items": {
        "ref": "#namedCount",
        "type": "ref"
      }
    },
    "topSearchTerms": {
      "type": "array",
      "items": {
        "ref": "#namedCount",
        "type": "ref"
      }
    },
    "impressionsOverTime": {
      "type": "array",
      "items": {
        "ref": "#impressionPoint",
        "type": "ref"
      }
    }
  }
}

engagement object

No description available.

Properties

avgScrollPct unknown Required

Mean scroll depth percentage (float; unknown-typed).

dailyUniques array of ref#timeseriesPoint Required

No description available.

dwellDistribution array of ref#namedCount Required

No description available.

tabEngagement array of ref#namedCount Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "dwellDistribution",
    "avgScrollPct",
    "tabEngagement",
    "dailyUniques"
  ],
  "properties": {
    "avgScrollPct": {
      "type": "unknown",
      "description": "Mean scroll depth percentage (float; unknown-typed)."
    },
    "dailyUniques": {
      "type": "array",
      "items": {
        "ref": "#timeseriesPoint",
        "type": "ref"
      }
    },
    "tabEngagement": {
      "type": "array",
      "items": {
        "ref": "#namedCount",
        "type": "ref"
      }
    },
    "dwellDistribution": {
      "type": "array",
      "items": {
        "ref": "#namedCount",
        "type": "ref"
      }
    }
  }
}

funnel object

No description available.

Properties

actions integer Required

No description available.

impressions integer Required

No description available.

pageviews integer Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "impressions",
    "pageviews",
    "actions"
  ],
  "properties": {
    "actions": {
      "type": "integer"
    },
    "pageviews": {
      "type": "integer"
    },
    "impressions": {
      "type": "integer"
    }
  }
}

impressionPoint object

Impressions on one day, split by discovery surface.

Properties

date string Required

No description available.

feed integer Required

No description available.

search integer Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "date",
    "search",
    "feed"
  ],
  "properties": {
    "date": {
      "type": "string"
    },
    "feed": {
      "type": "integer"
    },
    "search": {
      "type": "integer"
    }
  },
  "description": "Impressions on one day, split by discovery surface."
}

namedCount object

A labelled count, e.g. a feed name or search term with its total.

Properties

count integer Required

No description available.

name string Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "name",
    "count"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "count": {
      "type": "integer"
    }
  },
  "description": "A labelled count, e.g. a feed name or search term with its total."
}

recordTrendPoint object

Authoritative record-creation counts for one day.

Properties

date string Required

No description available.

likes integer Required

No description available.

listAdds integer Required

No description available.

reviews integer Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "date",
    "likes",
    "reviews",
    "listAdds"
  ],
  "properties": {
    "date": {
      "type": "string"
    },
    "likes": {
      "type": "integer"
    },
    "reviews": {
      "type": "integer"
    },
    "listAdds": {
      "type": "integer"
    }
  },
  "description": "Authoritative record-creation counts for one day."
}

timeseriesPoint object

A single day's value in a time series. `date` is 'YYYY-MM-DD' (UTC).

Properties

date string Required

No description available.

value integer Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "date",
    "value"
  ],
  "properties": {
    "date": {
      "type": "string"
    },
    "value": {
      "type": "integer"
    }
  },
  "description": "A single day's value in a time series. `date` is 'YYYY-MM-DD' (UTC)."
}

totals object

No description available.

Properties

avgDailyUniques unknown Required

Mean of per-day unique visitors across the range (float; unknown-typed).

avgDwellMs unknown Required

Mean dwell time in milliseconds (float; unknown-typed).

avgScrollPct unknown Required

Mean scroll depth percentage (float; unknown-typed).

clicks integer Required

No description available.

ctr unknown Required

clicks / impressions, 0..1 (float; unknown-typed).

impressions integer Required

No description available.

medianDwellMs unknown Required

Median dwell time in milliseconds (float; unknown-typed).

pageviews integer Required

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "impressions",
    "clicks",
    "pageviews",
    "ctr",
    "avgDwellMs",
    "medianDwellMs",
    "avgScrollPct",
    "avgDailyUniques"
  ],
  "properties": {
    "ctr": {
      "type": "unknown",
      "description": "clicks / impressions, 0..1 (float; unknown-typed)."
    },
    "clicks": {
      "type": "integer"
    },
    "pageviews": {
      "type": "integer"
    },
    "avgDwellMs": {
      "type": "unknown",
      "description": "Mean dwell time in milliseconds (float; unknown-typed)."
    },
    "impressions": {
      "type": "integer"
    },
    "avgScrollPct": {
      "type": "unknown",
      "description": "Mean scroll depth percentage (float; unknown-typed)."
    },
    "medianDwellMs": {
      "type": "unknown",
      "description": "Median dwell time in milliseconds (float; unknown-typed)."
    },
    "avgDailyUniques": {
      "type": "unknown",
      "description": "Mean of per-day unique visitors across the range (float; unknown-typed)."
    }
  }
}