# Reports ## Create Saved Report **post** `/print-mail/v1/reports` Create a new saved report definition. Saved reports are SQL queries that can be executed later to generate full exports or samples. If you just want to do ad-hoc queries, you should use the `/reports/samples` endpoint. ### Body Parameters - `sqlQuery: string` The SQL query defining the report. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Returns - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?" }' ``` #### Response ```json { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ``` ## Run Ad-hoc Query **post** `/print-mail/v1/reports/samples` Run an ad-hoc SQL query against your data lake and get a sample of the results. This is useful for quickly testing queries without saving them as a report. The query execution time and result size are limited. ### Body Parameters - `sqlQuery: string` The SQL query to execute for the sample. - `limit: optional number` Maximum number of rows to return in the sample. - `params: optional array of string` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). ### Returns - `ReportSample = object { id, records, report }` Represents the result of a report sample query. - `id: string` Unique identifier for the sample query result. - `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. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/samples \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "sqlQuery": "sqlQuery" }' ``` #### Response ```json { "id": "sample_abc", "report": "report_123", "records": [ { "id": "order_1" }, { "id": "order_2" } ] } ``` ## Update Report **post** `/print-mail/v1/reports/{id}` Update an existing saved report definition. You can change the query, description, or metadata. ### Path Parameters - `id: string` ### Body Parameters - `description: optional string` An optional user-friendly description for the report. Set to null to remove. - `metadata: optional map[string]` Optional key-value metadata associated with the report. Set to null to remove. - `sqlQuery: optional string` The SQL query defining the report. ### Returns - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ``` ## List Saved Reports **get** `/print-mail/v1/reports` Retrieve a list of saved reports for your organization. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of Report` - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ] } ``` ## Retrieve Saved Report **get** `/print-mail/v1/reports/{id}` Retrieve the details of a specific saved report by its ID. ### Path Parameters - `id: string` ### Returns - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "report_123", "object": "report", "live": false, "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?", "description": "Recent Orders", "metadata": { "team": "Sales" }, "createdAt": "2023-10-27T10:00:00Z", "updatedAt": "2023-10-27T10:00:00Z" } ``` ## Delete Saved Report **delete** `/print-mail/v1/reports/{id}` Delete a saved report definition. This action cannot be undone. Associated exports are not automatically deleted. ### Path Parameters - `id: string` ### Returns - `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. - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "report_123", "deleted": true } ``` ## Domain Types ### Deleted Response - `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. - `true` ### Report - `Report = object { id, createdAt, live, 5 more }` Represents a saved Report definition. - `id: string` Unique identifier for the report. - `createdAt: string` Timestamp when the report was created. - `live: boolean` Indicates if the report is associated with the live or test environment. - `object: "report"` Always `report`. - `"report"` - `sqlQuery: string` The SQL query defining the report. - `updatedAt: string` Timestamp when the report was last updated. - `description: optional string` An optional user-friendly description for the report. - `metadata: optional map[string]` Optional key-value metadata associated with the report. # Samples ## Sample a Saved Report **post** `/print-mail/v1/reports/{id}/samples` Run the query associated with a saved report and get a sample of the results. This allows getting up to 1000 rows of resutls but the runtime of the query is limited to 30 seconds. If you need more rows or longer runtime, you should create an export from this report. ### Path Parameters - `id: string` ### Body Parameters - `limit: optional number` Maximum number of rows to return in the sample. - `params: optional array of string` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). ### Returns - `ReportSample = object { id, records, report }` Represents the result of a report sample query. - `id: string` Unique identifier for the sample query result. - `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. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$ID/samples \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "sample_abc", "report": "report_123", "records": [ { "id": "order_1" }, { "id": "order_2" } ] } ``` ## Domain Types ### Report Sample - `ReportSample = object { id, records, report }` Represents the result of a report sample query. - `id: string` Unique identifier for the sample query result. - `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. ### Report Sample Create Base - `ReportSampleCreateBase = object { limit, params }` Base properties for creating a report sample. - `limit: optional number` Maximum number of rows to return in the sample. - `params: optional array of string` Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1). # Exports ## Create a Report Export **post** `/print-mail/v1/reports/{reportID}/exports` Create a new export job for a saved report. This runs the report's query asynchronously and generates a downloadable CSV file with the full results. Your queries can run for up to 13 minutes the resulting file can be up to 100mb large. ### Path Parameters - `reportID: string` ### Body Parameters - `description: optional string` An optional user-friendly description for the export. - `metadata: optional map[string]` Optional key-value metadata associated with the export. - `params: optional array of string` Optional parameters to bind to the SQL query of the associated report. ### Returns - `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. - `live: boolean` Indicates if the export is associated with the live or test environment. - `object: "report_export"` Always `report_export`. - `"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). - `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. - `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. - `sizeInBytes: optional number` The size of the generated export file in bytes. - `truncatedToBytes: optional number` If the output was truncated, indicates the byte limit reached. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "report_export_123", "object": "report_export", "live": false, "report": { "id": "report_123", "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?" }, "params": [ "2023-10-01T00:00:00Z" ], "description": "October Orders Export", "outputURL": "https://s3.amazonaws.com/...", "sizeInBytes": 1024, "rowCount": 50, "createdAt": "2023-10-27T11:00:00Z", "updatedAt": "2023-10-27T11:05:00Z" } ``` ## Get Report Export **get** `/print-mail/v1/reports/{reportID}/exports/{exportID}` Retrieve the status and details of a specific report export job. Check the `outputURL` property for the download link once generation is complete. ### Path Parameters - `reportID: string` - `exportID: string` ### Returns - `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. - `live: boolean` Indicates if the export is associated with the live or test environment. - `object: "report_export"` Always `report_export`. - `"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). - `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. - `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. - `sizeInBytes: optional number` The size of the generated export file in bytes. - `truncatedToBytes: optional number` If the output was truncated, indicates the byte limit reached. ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports/$EXPORT_ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "report_export_123", "object": "report_export", "live": false, "report": { "id": "report_123", "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?" }, "params": [ "2023-10-01T00:00:00Z" ], "description": "October Orders Export", "outputURL": "https://s3.amazonaws.com/...", "sizeInBytes": 1024, "rowCount": 50, "createdAt": "2023-10-27T11:00:00Z", "updatedAt": "2023-10-27T11:05:00Z" } ``` ## Delete Report Export **delete** `/print-mail/v1/reports/{reportID}/exports/{exportID}` Delete a completed or failed report export job and its associated output file (if any). This action cannot be undone. You cannot delete an export that is still generating. ### Path Parameters - `reportID: string` - `exportID: string` ### Returns - `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. - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/reports/$REPORT_ID/exports/$EXPORT_ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "report_export_123", "deleted": true } ``` ## Domain Types ### Report Export - `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. - `live: boolean` Indicates if the export is associated with the live or test environment. - `object: "report_export"` Always `report_export`. - `"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). - `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. - `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. - `sizeInBytes: optional number` The size of the generated export file in bytes. - `truncatedToBytes: optional number` If the output was truncated, indicates the byte limit reached.