> ## Documentation Index > Fetch the complete documentation index at: https://docs.merchantspring.io/llms.txt > Use this file to discover all available pages before exploring further. # List all sent and scheduled client reports > Retrieve a paginated list of client-deliverable reports that have been sent and/or are currently scheduled, each annotated with its sent/scheduled status and a link to view it. Saved report configurations that have never been sent or scheduled are excluded. Visibility is scoped by the caller's role: administrators and owners see every user's reports in the organisation, other roles see only their own. Sorted by createdAt descending unless sortKey/sortOrder are given. Requires the reportsOn entitlement on the API key's associated account. ## OpenAPI ````yaml /api-reference/openapi.json get /clientReports openapi: 3.0.1 info: title: MerchantSpring Public API version: 1.0.0 servers: - url: https://mm-api.merchantspring.io description: Production - url: https://mm-api-staging.merchantspring.io description: Staging security: [] tags: - name: advertising x-group: Advertising - name: channel x-group: Channel - name: content-change x-group: Content Change - name: custom-group x-group: Custom Group - name: order x-group: Order - name: product x-group: Product - name: report x-group: Report - name: vendor x-group: Vendor - name: tag x-group: Tag - name: search-query-performance x-group: Search Query Performance - name: client-report x-group: Client Report - name: profitability x-group: Profitability - name: targets x-group: Targets paths: /clientReports: get: tags: - client-report summary: List all sent and scheduled client reports description: >- Retrieve a paginated list of client-deliverable reports that have been sent and/or are currently scheduled, each annotated with its sent/scheduled status and a link to view it. Saved report configurations that have never been sent or scheduled are excluded. Visibility is scoped by the caller's role: administrators and owners see every user's reports in the organisation, other roles see only their own. Sorted by createdAt descending unless sortKey/sortOrder are given. Requires the reportsOn entitlement on the API key's associated account. operationId: listReports parameters: - name: pageIndex in: query description: >- Zero-based page index (default 0). A page beyond the last one returns 200 with an empty data array, not an error. schema: type: integer minimum: 0 default: 0 - name: pageSize in: query description: Number of results per page, max 100 (default 10). schema: type: integer minimum: 1 maximum: 100 default: 10 - name: sortKey in: query description: Response column to sort by (default createdAt). schema: type: string enum: - createdAt - reportName default: createdAt - name: sortOrder in: query description: Sort direction (default desc). schema: type: string enum: - asc - desc default: desc - name: reportName in: query description: Filter by report name (partial match) schema: type: string - name: channelId in: query description: >- Filter to reports configured for this store/channel. Not applicable for multi-channel reports, which are grouped by tag rather than a fixed set of channels. schema: type: string - name: merchantId in: query description: Filter to reports configured for this merchant ID schema: type: string - name: recipientEmail in: query description: >- Only show reports that are scheduled to, or have been sent to, this email address. schema: type: string - name: isSent in: query description: >- Filter to reports that have (or have not) ever been sent. Can be combined with isScheduled: isSent=true&isScheduled=true - sent and still scheduled; isSent=true&isScheduled=false - sent but no longer scheduled; isSent=false&isScheduled=true - scheduled but never sent; isSent=false&isScheduled=false - always empty. schema: type: boolean - name: isScheduled in: query description: >- Filter to reports that are (or are not) currently scheduled. Can be combined with isSent: isSent=true&isScheduled=true - sent and still scheduled; isSent=true&isScheduled=false - sent but no longer scheduled; isSent=false&isScheduled=true - scheduled but never sent; isSent=false&isScheduled=false - always empty. schema: type: boolean - name: fromDate in: query description: >- Start of date range, as Unix epoch seconds (not milliseconds). Filters on when the report record was created , not the date range the report's own data covers (see reportingPeriod in the response). Defaults to 30 days ago. required: false schema: type: integer - name: toDate in: query description: >- End of date range, as Unix epoch seconds (not milliseconds). Filters on when the report record was created , not the date range the report's own data covers (see reportingPeriod in the response). Defaults to now. The range must not exceed 6 months; passing milliseconds instead of seconds is a common cause of an unexpected "Date range must not exceed 6 months" error. required: false schema: type: integer responses: '200': description: Successful operation headers: Access-Control-Allow-Origin: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ListReportsResponse' '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidSortKey: summary: sortKey is not one of the supported values value: status: error error: 'sortKey must be one of: createdAt, reportName' invalidRecipientEmail: summary: recipientEmail is not a valid email address value: status: error error: recipientEmail must be a valid email invalidPageSize: summary: pageSize is not a positive integer value: status: error error: pageSize must be a positive integer invalidDateRange: summary: toDate is before fromDate value: status: error error: toDate must not be before fromDate dateRangeTooWide: summary: fromDate/toDate range exceeds 6 months value: status: error error: Date range must not exceed 6 months '403': description: >- Either a missing/invalid x-api-key, or an authenticated account that lacks the Client Reports entitlement. The two cases have different response shapes - see examples. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/ApiGatewayForbiddenResponse' examples: notEntitled: summary: Account has no Client Reports (reportsOn) entitlement value: status: error error: >- Unauthorized: account does not have permission to access this endpoint invalidApiKey: summary: Missing or invalid x-api-key value: message: Forbidden security: - api_key: [] components: schemas: ListReportsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ReportItem' pagination: type: object properties: pageIndex: type: integer description: Zero-based page index pageSize: type: integer description: Number of results per page count: type: integer description: Total number of matching reports example: pagination: pageIndex: 0 pageSize: 10 count: 1 data: - reportId: 6a72ba589131de9029111111 reportName: Report Demo reportType: SINGLE channels: - channelId: '1' channelName: Seller Demo (USA) merchantId: XXXUS @ ATVPDKIKX0DER marketplaceType: amazon marketplaceSubtype: amazon marketplaceCountry: USA recipients: - demo@merchantspring.com.au selectedTags: null reportingPeriod: period: LAST12 fromDate: '2025-08-01T07:00:00.000Z' toDate: '2026-08-01T06:59:59.000Z' comparisonPeriod: THISYEAR priorFromDate: '2024-08-01T07:00:00.000Z' priorToDate: '2025-08-01T06:59:59.000Z' timezone: Australia/Sydney interval: MONTH schedule: frequency: m reportingDelay: 4 reportDay: 5th reportHour: 6 isSent: true isScheduled: true reportUrl: https://merchantspring.io/report?id=6a72ba589131de9029111111 createdAt: '2026-08-05T04:21:44.503Z' updatedAt: null ErrorResponse: type: object properties: status: type: string enum: - error error: type: string description: >- Human-readable message. Validation failures list every failing rule, comma-separated. example: status: error error: Invalid request parameters ApiGatewayForbiddenResponse: type: object description: Returned for a missing or invalid x-api-key. properties: message: type: string enum: - Forbidden example: message: Forbidden ReportItem: type: object properties: reportId: type: string description: Unique ID of this saved report configuration reportName: type: string description: Name of the report reportType: type: string enum: - SINGLE - MULTI description: Whether the report covers a single store or multiple stores channels: type: array items: $ref: '#/components/schemas/ReportChannel' nullable: true description: >- The report's fixed list of channels - only set for reportType SINGLE. Null for reportType MULTI, where channels are resolved from selectedTags when the report is viewed rather than from a fixed list. recipients: type: array items: type: string description: >- Who receives this report. For a scheduled report, the people currently on the schedule. Otherwise, everyone it has been sent to. Included intentionally as this only ever reflects recipients for a report the caller is already allowed to see, which is always scoped to the caller's own organisation. selectedTags: type: array items: type: string nullable: true description: >- Tags this report's channels are selected by - only set for reportType MULTI. Null for reportType SINGLE. reportingPeriod: $ref: '#/components/schemas/ReportingPeriod' schedule: $ref: '#/components/schemas/ReportSchedule' isSent: type: boolean description: Whether this report has ever been sent (ad-hoc or via a schedule) isScheduled: type: boolean description: Whether this report is currently scheduled reportUrl: type: string description: >- Deep link to view the report (requires a browser session). Included intentionally as this is the same shareable link a user would get from the product itself, meant to be passed around and opened by anyone with access. createdAt: type: string format: date-time updatedAt: type: string format: date-time nullable: true description: >- When the report config was last updated - null if never updated since creation ReportChannel: type: object properties: channelId: type: string description: Store/channel ID channelName: type: string description: Store display name merchantId: type: string description: Merchant ID marketplaceType: type: string description: Marketplace type (e.g. amazon, walmart) marketplaceSubtype: type: string description: Marketplace subtype (e.g. amazon, amazon_vendor) marketplaceCountry: type: string description: Marketplace country code ReportingPeriod: type: object properties: period: type: string enum: - TODAY - YESTERDAY - WTD - WTDMTS - LAST30 - MTD - CURRENTMONTH - LASTMONTH - CURRENTQ - LASTQ - LAST12 - YTD - CURRENTYEAR - CUSTOM description: The report's date range, e.g. LAST12 for the trailing 12 months. fromDate: type: string format: date-time description: Start of the report's date range. toDate: type: string format: date-time description: End of the report's date range. comparisonPeriod: type: string enum: - THISYEAR - LASTYEAR - PREVIOUSFISCALPERIOD description: The period the report is compared against, e.g. LASTYEAR. priorFromDate: type: string format: date-time nullable: true description: >- Start of the comparison date range. Null when the report has no comparison range stored. priorToDate: type: string format: date-time nullable: true description: >- End of the comparison date range. Null when the report has no comparison range stored. timezone: type: string description: Timezone used for the report's dates, e.g. 'Australia/Sydney'. interval: type: string nullable: true description: >- How the data is grouped in charts, e.g. by day, week, or month. Null if not applicable. ReportSchedule: type: object properties: frequency: type: string nullable: true enum: - d - w - m - null description: >- How often the report is sent: daily, weekly, or monthly. Null when isScheduled is false. reportingDelay: type: integer nullable: true description: >- Number of days between the scheduled reporting date and when the report is sent. For example, on a monthly schedule, a reportingDelay of 4 sends the report on the 5th of each month. example: 4 reportDay: type: string nullable: true description: >- Day the report is sent on. For weekly schedules, a weekday like 'Mon'. For monthly schedules, a day of month like '5th'. Not used for daily schedules. Null when isScheduled is false. reportHour: type: integer nullable: true description: >- Hour of day (0-23, local to timezone) the schedule sends at - only set when isScheduled is true securitySchemes: api_key: type: apiKey name: x-api-key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.