Reports

The reports API lets you run SQL queries against a data lake with all of your PostGrid data. You can use this to run ad-hoc SQL queries or save them as reports. You can bulk export data from these reports to fit all of your reporting needs. A saved report can also carry a schedule, in which case PostGrid runs it for you on that cadence, producing an export each time and optionally emailing recipients you nominate. If your organization has sub-organizations, PostGrid can include their data in your data lake so that a single query spans your whole hierarchy — every table then carries an organization column identifying the organization each row belongs to. Contact support@postgrid.com to enable this. Note that the data this API provides may be up to 2 hours behind your current PostGrid environment. Your test and live data lakes are fully segregated, so you’ll need a live API key to run queries against your live data.

You can request access to this to this feature by reaching out to support@postgrid.com

Create Saved Report

POST/print-mail/v1/reports

Run Ad-hoc Query

POST/print-mail/v1/reports/samples

Update Report

POST/print-mail/v1/reports/{id}

List Saved Reports

GET/print-mail/v1/reports

Retrieve Saved Report

GET/print-mail/v1/reports/{id}

Delete Saved Report

DELETE/print-mail/v1/reports/{id}

Preview a Report Schedule

POST/print-mail/v1/reports/schedule_previews

ModelsExpand Collapse

DeletedResponse object { id, deleted }

Generic response for delete operations.

id: string

The ID of the deleted resource.

deleted: true

Indicates the resource was successfully deleted.

Report object { id, createdAt, live, 6 more }

Represents a saved Report definition.

id: string

Unique identifier for the report.

createdAt: string

Timestamp when the report was created.

formatdate-time

live: boolean

Indicates if the report is associated with the live or test environment.

object: "report"

Always report.

sqlQuery: string

The SQL query defining the report.

updatedAt: string

Timestamp when the report was last updated.

formatdate-time

description: optional string

An optional user-friendly description for the report.

metadata: optional map[string]

Optional key-value metadata associated with the report.

schedule: optional ReportSchedule { frequency, nextRun, description, 2 more }

The schedule stored on a saved report.

frequency: string

The cadence as a number + unit, for example 1h, 2d, or 1m.

nextRun: string

The next time this report will run.

formatdate-time

description: optional string

The cadence in words, for example Every 2 weeks on Monday at 9:00 AM (America/Toronto).

notificationEmails: optional array of string

Addresses emailed when a run finishes.

spec: optional ScheduleSpec { interval, time, unit, 4 more }

How often a saved report should run itself. Times are interpreted in the America/Toronto timezone, and the smallest supported cadence is one hour.

interval: number

How many units pass between runs — the 2 in “every 2 weeks”.

formatint32

minimum1

time: string

The 24-hour HH:mm time of day the report runs, in America/Toronto.

unit: "h" or "d" or "w" or 2 more

The cadence units a report schedule may use: hour, day, week, month, or year.

One of the following:

"h"

"d"

"w"

"m"

"y"

dayOfMonth: optional number

Monthly and yearly schedules only. Monthly schedules are capped at 28 so a run never skips a short month.

formatint32

minimum1

maximum31

dayOfWeek: optional number

Weekly schedules only. 0 is Sunday through 6 for Saturday.

formatint32

minimum0

maximum6

month: optional number

Yearly schedules only. 0 is January through 11 for December.

formatint32

minimum0

maximum11

notificationEmails: optional array of string

Up to 10 addresses to email when a run finishes. Each must belong to a user in the same organization as the report; others are skipped. Omit or pass an empty array to send no email.

ReportSchedule object { frequency, nextRun, description, 2 more }

The schedule stored on a saved report.

frequency: string

The cadence as a number + unit, for example 1h, 2d, or 1m.

nextRun: string

The next time this report will run.

formatdate-time

description: optional string

The cadence in words, for example Every 2 weeks on Monday at 9:00 AM (America/Toronto).

notificationEmails: optional array of string

Addresses emailed when a run finishes.

spec: optional ScheduleSpec { interval, time, unit, 4 more }

How often a saved report should run itself. Times are interpreted in the America/Toronto timezone, and the smallest supported cadence is one hour.

interval: number

How many units pass between runs — the 2 in “every 2 weeks”.

formatint32

minimum1

time: string

The 24-hour HH:mm time of day the report runs, in America/Toronto.

unit: "h" or "d" or "w" or 2 more

The cadence units a report schedule may use: hour, day, week, month, or year.

One of the following:

"h"

"d"

"w"

"m"

"y"

dayOfMonth: optional number

Monthly and yearly schedules only. Monthly schedules are capped at 28 so a run never skips a short month.

formatint32

minimum1

maximum31

dayOfWeek: optional number

Weekly schedules only. 0 is Sunday through 6 for Saturday.

formatint32

minimum0

maximum6

month: optional number

Yearly schedules only. 0 is January through 11 for December.

formatint32

minimum0

maximum11

notificationEmails: optional array of string

Up to 10 addresses to email when a run finishes. Each must belong to a user in the same organization as the report; others are skipped. Omit or pass an empty array to send no email.

SchedulePreview object { dayOfMonth, dayOfMonthOptions, description, 4 more }

The cadence PostGrid derived from a schedule, returned without saving anything. Useful for confirming when a schedule would actually run.

dayOfMonth: number

The day of the month the schedule resolved to, clamped to a day that exists.

formatint32

dayOfMonthOptions: array of object { label, value }

The days of the month this cadence may be anchored to, with display labels.

label: string

The day as an ordinal, for example 15th.

value: number

The day of the month.

formatint32

description: string

The cadence in words, for example Every 2 weeks on Monday at 9:00 AM (America/Toronto).

firstRunLabel: string

The first run as an absolute instant, for example Monday, June 15, 2026 at 9:00 AM.

frequency: string

The cadence as a number + unit, for example 1h or 2d.

nextRun: string

When the report would run next.

formatdate-time

queryHasParameters: boolean

True if the supplied sqlQuery uses parameters, which makes it unschedulable.

ScheduleSpec object { interval, time, unit, 4 more }

How often a saved report should run itself. Times are interpreted in the America/Toronto timezone, and the smallest supported cadence is one hour.

interval: number

How many units pass between runs — the 2 in “every 2 weeks”.

formatint32

minimum1

time: string

The 24-hour HH:mm time of day the report runs, in America/Toronto.

unit: "h" or "d" or "w" or 2 more

The cadence units a report schedule may use: hour, day, week, month, or year.

One of the following:

"h"

"d"

"w"

"m"

"y"

dayOfMonth: optional number

Monthly and yearly schedules only. Monthly schedules are capped at 28 so a run never skips a short month.

formatint32

minimum1

maximum31

dayOfWeek: optional number

Weekly schedules only. 0 is Sunday through 6 for Saturday.

formatint32

minimum0

maximum6

month: optional number

Yearly schedules only. 0 is January through 11 for December.

formatint32

minimum0

maximum11

notificationEmails: optional array of string

Up to 10 addresses to email when a run finishes. Each must belong to a user in the same organization as the report; others are skipped. Omit or pass an empty array to send no email.

ReportsSamples

You can request access to this to this feature by reaching out to support@postgrid.com

Sample a Saved Report

POST/print-mail/v1/reports/{id}/samples

ModelsExpand Collapse

ReportSample object { id, object, records, report }

Represents the result of a report sample query.

id: string

Unique identifier for the sample query result.

object: "report_sample"

Always report_sample.

records: array of map[unknown]

The actual data records returned by the sample query.

report: string

The ID of the report this sample was generated from, or null for ad-hoc samples.

ReportSampleCreateBase object { limit, params }

Base properties for creating a report sample.

limit: optional number

Maximum number of rows to return in the sample.

formatint32

maximum1000

params: optional array of string

Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

ReportsExports

You can request access to this to this feature by reaching out to support@postgrid.com

ModelsExpand Collapse

ReportExport object { id, createdAt, live, 11 more }

Represents a report export job and its results.

id: string

Unique identifier for the report export.

createdAt: string

Timestamp when the export was created.

formatdate-time

live: boolean

Indicates if the export is associated with the live or test environment.

object: "report_export"

Always report_export.

report: object { id, sqlQuery }

Details of the report this export was generated from.

id: string

The ID of the report.

sqlQuery: string

The SQL query used for this export (snapshotted at creation time).

updatedAt: string

Timestamp when the export was last updated (e.g., finished generation).

formatdate-time

description: optional string

An optional user-friendly description for the export.

failureMessage: optional string

If export generation failed, this contains the error message.

metadata: optional map[string]

Optional key-value metadata associated with the export.

outputURL: optional string

A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

formaturi

params: optional array of string

Optional parameters to bind to the SQL query of the associated report.

rowCount: optional number

The number of rows in the exported data.

formatint64

sizeInBytes: optional number

The size of the generated export file in bytes.

formatint64

truncatedToBytes: optional number

If the output was truncated, indicates the byte limit reached.

formatint64

Reports

Create Saved Report

Run Ad-hoc Query

Update Report

List Saved Reports

Retrieve Saved Report

Delete Saved Report

Preview a Report Schedule

ModelsExpand Collapse

ReportsSamples

Sample a Saved Report

ModelsExpand Collapse

ReportsExports

Create a Report Export

List Report Exports

Get Report Export

Delete Report Export

ModelsExpand Collapse