Report Data & Aggregations

A report is a query surface as well as a saved configuration. Once a report has data sources, the Report type exposes five read fields — records (the combined record list), recordCount (the matching count), todos (the record list as Todo objects), todoCount (the matching count as Todo objects), and aggregations (per-field statistics) — plus the refreshReportAggregations mutation, which invalidates the cached aggregation results.

All five read fields run with the report creator’s workspace permissions (not the caller’s) and combine every data source on the report, so the data you read is identical for every viewer regardless of which workspaces they can see. See Query Reports for reading a report’s metadata and configuration, and Create a Report for setting up its data sources.

Request

Read the combined record list, count, and a sum/avg over a numeric custom field in one query:

query ReadReportData {
  report(id: "report_123") {
    todoCount
    todos(limit: 50, sort: [duedAt_ASC]) {
      id
      title
      done
      duedAt
      users {
        fullName
      }
    }
    aggregations(fields: [{ field: "field_123", fieldType: "number" }]) {
      field
      fieldName
      sum
      avg
      min
      max
      count
    }
  }
}

report is identified by the report’s id. records, recordCount, todos, todoCount, and aggregations are fields on the resolved Report, so they are always nested under a report (or reports) query.

Parameters

These fields share the records TodosFilter and TodosSort inputs rather than redefining them. See the Records section for the full field-by-field reference of those inputs — only the report-specific behavior is documented here.

Report.todos arguments

Report.todoCount arguments

Report.records arguments

ReportRecord

ReportRecord is Report.records’ flat projection of a record. It carries the same record data as Todo, plus the home table: databaseId and databaseName name the record’s table.

Report.recordCount arguments

Report.aggregations arguments

AggregationFieldInput

Response

{
  "data": {
    "report": {
      "todoCount": 128,
      "todos": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "title": "Renew enterprise contract",
          "done": false,
          "duedAt": "2026-06-02T00:00:00.000Z",
          "users": [{ "fullName": "Dana Reyes" }]
        },
        {
          "id": "clm4r2abc000108l0aaaa1111",
          "title": "Q3 onboarding kickoff",
          "done": true,
          "duedAt": "2026-06-05T00:00:00.000Z",
          "users": []
        }
      ],
      "aggregations": [
        {
          "field": "field_123",
          "fieldName": "Deal Value",
          "sum": 184500,
          "avg": 1441.4,
          "min": 0,
          "max": 50000,
          "count": 128
        }
      ]
    }
  }
}

FieldAggregation

todos returns [Todo!]! — select any field on Todo (see the Records section for the full type). records returns [ReportRecord!]! — a flat projection of each record; see the ReportRecord table above. recordCount and todoCount return a bare Int!. aggregations returns [FieldAggregation!]!, one entry per requested field, in the same order.

Empty reports

A report with no data sources is valid but has nothing to read:

• records and todos return an empty list [].
• recordCount and todoCount return 0.
• aggregations returns an empty list [].

No error is raised in any of these cases. Add data sources with Create a Report or Manage Report Access before expecting results.

Refreshing cached aggregations

aggregations results are cached in Redis (in 5-minute buckets) to keep large reports fast. Use the refreshReportAggregations mutation to discard that cache when the underlying records have changed and you need the next read to recompute.

mutation RefreshReportAggregations {
  refreshReportAggregations(reportId: "report_123") {
    id
    lastGeneratedAt
  }
}

refreshReportAggregations arguments

{
  "data": {
    "refreshReportAggregations": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "lastGeneratedAt": "2026-05-29T12:00:00.000Z"
    }
  }
}

Errors

Reading data via report { records / recordCount / todos / todoCount / aggregations } is gated by the parent report query’s visibility check, which raises REPORT_NOT_FOUND when the report is invisible to you. refreshReportAggregations performs the same view-access check before touching the cache.

Permissions

• Reading records / recordCount / todos / todoCount / aggregations — requires view access to the parent report: you must be its createdBy or appear in its reportUsers (either EDITOR or VIEWER). The records themselves are resolved with the report creator’s workspace permissions, so a VIEWER who cannot see a given workspace directly still sees its records through the report.
• refreshReportAggregations — requires only view access (creator or any shared user, EDITOR or VIEWER). It is intentionally looser than modifying the report; invalidating the cache is a read-side operation.

Modifying or deleting a report requires higher tiers — see Manage Report Access and Duplicate & Delete a Report.

Related

• Reports overview
• Create a Report
• Query Reports
• Manage Report Access
• Export a Report
• Records