Skip to main content


Query a Metric in leaderboard format. A table (array of rows) with the selected dimensions and corresponding Metric values for the given time range and filters.


  • input required LeaderboardInput

    The fields for querying a Metric in leaderboard format.

    A Metric's leaderboard query returns an ordered table of Dimension and Metric values over a given time range.

    • input.metric optional MetricInput

      The Metric to query. You can query a pre-configured Metric by ID or name, or you can query an ad hoc Metric that you define inline.

    • input.timeRange required TimeRangeInput

      The time range for calculating the leaderboard.

    • input.timeZone optional String

      The time zone to use. Dates and times are always returned in UTC, but setting the time zone influences relative time ranges and granularities.

      You can set this to "America/Los_Angeles", "Europe/Berlin", or any other value in the IANA time zone database. Defaults to "UTC".

    • input.dimensions required array of DimensionInput

      One or many Dimensions to group the Metric values by. Typically, Dimensions in a leaderboard are what you want to compare and rank.

    • input.sort optional Sort

      The sort order of the rows. It can be ascending (ASC) or descending (DESC) order. Defaults to descending (DESC) order when not provided.

      The available sort orders.

      • ASC

        Sort in ascending order.

      • DESC

        Sort in descending order.

    • input.rowLimit required Int

      The number of rows to be returned. It can be a number between 1 and 1,000.

    • input.filters optional array of FilterInput

      The list of filters to apply before retrieving the leaderboard data. If no Query Filters are provided, all data is included.

    • input.propeller optional Propeller

      Optionally specifies the Propeller to use. This can be set by Users when querying from the Metric Playground or GraphQL Explorer. Applications may not set this value. Instead, Application Queries always use the Propeller configured on the Application.

      A Propeller determines your Application's query processing power. The larger the Propeller, the faster the queries and the higher the cost. Every Propel Application (and therefore every set of API credentials) has a Propeller that determines the speed and cost of queries.

      Learn more about Data Sources.

      • P1_X_SMALL

        Max records per second: 5,000,000 records per second

      • P1_SMALL

        Max records per second: 25,000,000 records per second

      • P1_MEDIUM

        Max records per second: 100,000,000 records per second

      • P1_LARGE

        Max records per second: 250,000,000 records per second

      • P1_X_LARGE

        Max records per second: 500,000,000 records per second


Nullable LeaderboardResponse

The leaderboard response object. It contains an array of headers and a table (array of rows) with the selected Dimensions and corresponding Metric values for the given time range and Query Filters.

  • leaderboard.headers non-null array of String

    The table headers. It contains the Dimension and Metric names.

  • leaderboard.rows non-null array of String

    An ordered array of rows. Each row contains the Dimension values and the corresponding Metric value. A Dimension value can be empty. A Metric value will never be empty.

  • leaderboard.query non-null QueryInfo

    The Query statistics and metadata.