Get info about document size

Ask for Help
1

Hi!

I would like to get the documents sizes info in order to identiy the biggest ones but I haven’t found any API endpoints for this.
Is there another way to do this maybe?

Cheers!

3

Also if you have access to the Grist installation, then the query:

select id, usage from docs

on the home database for the installation will give you all the stats shown on the Raw Data page, for each doc.

1 Like
4

Hi Heloise.

This is a very insightful question! You are looking for document metadata that tends to be associated with system performance and limits, which often isn’t exposed through the standard document content API endpoints.

While the primary REST API endpoints designed for fetching or modifying document content typically do not list overall size, the size metrics you are seeking are recorded and visible in specific areas of Grist, especially for administrators or via background usage events.

Here are the ways you can retrieve or view document size information, drawing from the source material:

1. The Direct In-Product Method (Raw Data Page)

The easiest way to check the size of a specific document within the Grist application interface is through the Raw Data page.

  • The Raw Data page lists all data tables and summarizes your document’s usage statistics.

  • The Usage statistics are summarized beneath the list of data tables.

  • This section will display the document’s current data size, which applies to the entire document. This data size corresponds approximately to the size the data would be in CSV format (e.g., the Pro plan limit is 200MB).

  • This is also where you can check your document’s attachment usage.

2. The Administrative/API Method (For Hosted or Self-Managed Instances)

For users with administrative access, particularly on Enterprise or self-hosted installations, Grist does track detailed document size metrics under usage data:

A. Admin Controls Interface (Enterprise Plans)

If you are an installation administrator, the Admin Controls feature (available on all Enterprise plans, whether Grist-managed or self-hosted) provides detailed resource views.

  • The Documents page within Admin Controls lists all documents across your organizations.

  • This list includes three key usage metrics for identifying document size: Usage Rows, Usage Data Bytes, and Usage Attachment Bytes.

  • It is important to note that this document usage data is not real-time; it is updated periodically while a document is open.

B. Telemetry Logs

If telemetry is enabled (especially at the full or limited level for self-hosters), document usage information is actively recorded in a programmatic format that could be exported and analyzed:

  • The documentUsage event is triggered on document open and close, as well as hourly while a document is open.

  • This event contains fields providing exact size information:

    • dataSizeBytes: The total size of all data in the document, excluding attachments.

    • attachmentsSize: The total size of all attachments in the document.

    • It also includes the rowCount.

3. Alternative for Reducing File Size (Download Option)

If you are looking for large documents in order to perform backups or transfers efficiently, you can manipulate the document history upon download:

  • Grist documents can be downloaded in their entirety as an SQLite database file with a .grist extension.
  • When downloading the document via the REST API or the UI, you have the option to include a nohistory query parameter. Downloading a .grist file without document history (or structure only, for templates) can significantly reduce the file size. In tests, omitting file history resulted in one document size dropping from 10.8mb to 1.5mb.