API Reference

Print Mail

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

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

print_mail.reports.create(ReportCreateParams**kwargs) -> Report

POST/print-mail/v1/reports

Run Ad-hoc Query

print_mail.reports.sample(ReportSampleParams**kwargs) -> ReportSample

POST/print-mail/v1/reports/samples

Update Report

print_mail.reports.update(strid, ReportUpdateParams**kwargs) -> Report

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

List Saved Reports

print_mail.reports.list(ReportListParams**kwargs) -> SyncSkipLimit[Report]

GET/print-mail/v1/reports

Retrieve Saved Report

print_mail.reports.retrieve(strid) -> Report

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

Delete Saved Report

print_mail.reports.delete(strid) -> DeletedResponse

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

Preview a Report Schedule

print_mail.reports.preview_schedule(ReportPreviewScheduleParams**kwargs) -> SchedulePreview

POST/print-mail/v1/reports/schedule_previews

ModelsExpand Collapse

class DeletedResponse: …

Generic response for delete operations.

id: str

The ID of the deleted resource.

deleted: Literal[true]

Indicates the resource was successfully deleted.

class Report: …

Represents a saved Report definition.

id: str

Unique identifier for the report.

created_at: datetime

Timestamp when the report was created.

formatdate-time

live: bool

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

object: Literal["report"]

Always report.

sql_query: str

The SQL query defining the report.

updated_at: datetime

Timestamp when the report was last updated.

formatdate-time

description: Optional[str]

An optional user-friendly description for the report.

metadata: Optional[Dict[str, str]]

Optional key-value metadata associated with the report.

schedule: Optional[ReportSchedule]

The schedule stored on a saved report.

frequency: str

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

next_run: datetime

The next time this report will run.

formatdate-time

description: Optional[str]

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

notification_emails: Optional[List[str]]

Addresses emailed when a run finishes.

spec: Optional[ScheduleSpec]

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: int

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

formatint32

minimum1

time: str

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

unit: Literal["h", "d", "w", 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"

day_of_month: Optional[int]

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

formatint32

minimum1

maximum31

day_of_week: Optional[int]

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

formatint32

minimum0

maximum6

month: Optional[int]

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

formatint32

minimum0

maximum11

notification_emails: Optional[List[str]]

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.

class ReportSchedule: …

The schedule stored on a saved report.

frequency: str

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

next_run: datetime

The next time this report will run.

formatdate-time

description: Optional[str]

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

notification_emails: Optional[List[str]]

Addresses emailed when a run finishes.

spec: Optional[ScheduleSpec]

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: int

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

formatint32

minimum1

time: str

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

unit: Literal["h", "d", "w", 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"

day_of_month: Optional[int]

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

formatint32

minimum1

maximum31

day_of_week: Optional[int]

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

formatint32

minimum0

maximum6

month: Optional[int]

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

formatint32

minimum0

maximum11

notification_emails: Optional[List[str]]

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.

class SchedulePreview: …

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

day_of_month: int

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

formatint32

day_of_month_options: List[DayOfMonthOption]

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

label: str

The day as an ordinal, for example 15th.

value: int

The day of the month.

formatint32

description: str

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

first_run_label: str

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

frequency: str

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

next_run: datetime

When the report would run next.

formatdate-time

query_has_parameters: bool

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

class ScheduleSpec: …

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: int

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

formatint32

minimum1

time: str

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

unit: Literal["h", "d", "w", 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"

day_of_month: Optional[int]

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

formatint32

minimum1

maximum31

day_of_week: Optional[int]

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

formatint32

minimum0

maximum6

month: Optional[int]

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

formatint32

minimum0

maximum11

notification_emails: Optional[List[str]]

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

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

Sample a Saved Report

print_mail.reports.samples.create(strid, SampleCreateParams**kwargs) -> ReportSample

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

ModelsExpand Collapse

class ReportSample: …

Represents the result of a report sample query.

id: str

Unique identifier for the sample query result.

object: Literal["report_sample"]

Always report_sample.

records: List[Dict[str, object]]

The actual data records returned by the sample query.

report: Optional[str]

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

class ReportSampleCreateBase: …

Base properties for creating a report sample.

limit: Optional[int]

Maximum number of rows to return in the sample.

formatint32

maximum1000

params: Optional[List[str]]

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

ReportsExports

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 a Report Export

print_mail.reports.exports.create(strreport_id, ExportCreateParams**kwargs) -> ReportExport

POST/print-mail/v1/reports/{reportID}/exports

List Report Exports

print_mail.reports.exports.list(strreport_id, ExportListParams**kwargs) -> SyncSkipLimit[ReportExport]

GET/print-mail/v1/reports/{reportID}/exports

Get Report Export

print_mail.reports.exports.retrieve(strexport_id, ExportRetrieveParams**kwargs) -> ReportExport

GET/print-mail/v1/reports/{reportID}/exports/{exportID}

Delete Report Export

print_mail.reports.exports.delete(strexport_id, ExportDeleteParams**kwargs) -> DeletedResponse

DELETE/print-mail/v1/reports/{reportID}/exports/{exportID}

ModelsExpand Collapse

class ReportExport: …

Represents a report export job and its results.

id: str

Unique identifier for the report export.

created_at: datetime

Timestamp when the export was created.

formatdate-time

live: bool

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

object: Literal["report_export"]

Always report_export.

report: Report

Details of the report this export was generated from.

id: str

The ID of the report.

sql_query: str

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

updated_at: datetime

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

formatdate-time

description: Optional[str]

An optional user-friendly description for the export.

failure_message: Optional[str]

If export generation failed, this contains the error message.

metadata: Optional[Dict[str, str]]

Optional key-value metadata associated with the export.

output_url: Optional[str]

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

formaturi

params: Optional[List[str]]

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

row_count: Optional[int]

The number of rows in the exported data.

formatint64

size_in_bytes: Optional[int]

The size of the generated export file in bytes.

formatint64

truncated_to_bytes: Optional[int]

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

formatint64