> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List reports > Returns reports using the existing filter and cursor pagination semantics. ## OpenAPI ````yaml en/openapi/v3-current/reporter.yaml get /v1/reports openapi: 3.1.0 info: contact: name: Discord community url: https://discord.gg/DnhqKwkGv3 description: >- This is OpenAPI documentation for Reporter. The unified reporter binary serves the REST API (RUN_MODE=api) and/or the RabbitMQ report-generation worker (RUN_MODE=worker); RUN_MODE=all runs both in one process for local development. All REST endpoints documented here serve only when RUN_MODE=api or all (port :4005); the worker (port :4006) exposes health/readyz only. license: name: Lerian Studio General License title: Midaz Reporter API version: 4.0.0 servers: - url: http://localhost:4005 - url: https://localhost:4005 security: - BearerAuth: [] tags: - description: Generated report instances and their lifecycle. name: Reports - description: Reusable report definitions. name: Templates - description: Interactive construction of report templates. name: Template Builder - description: Scheduled report due-date tracking. name: Deadlines - description: Configured inputs that feed report data. name: Data Sources - description: Aggregated reporting metrics. name: Metrics - description: Published business event catalog and delivery policies. name: Streaming paths: /v1/reports: get: tags: - Reports summary: List reports description: >- Returns reports using the existing filter and cursor pagination semantics. operationId: listReports parameters: - description: Report status example: Finished in: query name: status schema: type: string - description: Template UUID; templateId is also accepted example: 00000000-0000-0000-0000-000000000000 in: query name: template_id schema: format: uuid type: string - description: Creation date in YYYY-MM-DD format; createdAt is also accepted example: '2026-01-31' in: query name: created_at schema: format: date type: string - description: Filter window start in YYYY-MM-DD format example: '2026-01-01' in: query name: start_date schema: format: date type: string - description: Filter window end in YYYY-MM-DD format example: '2026-01-31' in: query name: end_date schema: format: date type: string - description: Report description filter example: Monthly report in: query name: description schema: type: string - description: Report output format example: PDF in: query name: output_format schema: enum: - PDF - HTML - XML - TXT - CSV type: string - description: Active flag filter example: true in: query name: active schema: type: boolean - description: Report type filter example: regulatory in: query name: type schema: type: string - description: Opaque cursor for cursor-based pagination example: eyJpZCI6IjEyMyJ9 in: query name: cursor schema: type: string - description: Sort order example: desc in: query name: sort_order schema: default: desc enum: - asc - desc type: string - description: Page size example: 10 in: query name: limit schema: default: 10 type: integer - description: Page number example: 1 in: query name: page schema: default: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListReportsHumaOutputBody' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unauthorized '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Forbidden '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error components: schemas: ListReportsHumaOutputBody: properties: items: description: Reports in the current page examples: - - completedAt: '2026-01-31T15:04:05Z' createdAt: '2026-01-31T15:00:00Z' deletedAt: '2026-02-01T09:00:00Z' filters: {} id: 00000000-0000-0000-0000-000000000001 metadata: {} status: Finished templateId: 00000000-0000-0000-0000-000000000002 templateOutputFormat: PDF updatedAt: '2026-01-31T15:04:05Z' items: $ref: '#/components/schemas/Report' type: - array - 'null' limit: description: Maximum number of reports in the page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Number of reports returned examples: - 10 format: int64 type: integer type: object Detail: properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details examples: - - location: body.templateId message: expected string to match 'uuid' format value: not-a-uuid items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object Report: properties: completedAt: description: Time when report generation completed, when available. examples: - '2026-01-31T15:04:05Z' format: date-time type: - string - 'null' createdAt: description: Time when the report was created. examples: - '2026-01-31T15:00:00Z' format: date-time type: string deletedAt: description: Time when the report was soft-deleted, when applicable. examples: - '2026-02-01T09:00:00Z' format: date-time type: - string - 'null' filters: additionalProperties: additionalProperties: additionalProperties: $ref: '#/components/schemas/FilterCondition' type: object type: object description: Filter conditions grouped by data source, table, and field. examples: - accounts: account: status: eq: - ACTIVE type: object id: description: Stable report identifier. examples: - 00000000-0000-0000-0000-000000000001 type: string metadata: additionalProperties: {} description: Additional report metadata keyed by attribute name. examples: - source: ledger tenant: sandbox type: object status: description: Current report generation status. examples: - Processing type: string templateDescription: description: Description copied from the template when the report was created. examples: - Monthly accounting report type: string templateId: description: Template snapshot source identifier. examples: - 00000000-0000-0000-0000-000000000002 type: string templateOutputFormat: description: Output format selected for the generated report. examples: - pdf type: string updatedAt: description: Time when the report was last updated. examples: - '2026-01-31T15:04:05Z' format: date-time type: string type: object ErrorDetail: properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' examples: - body.templateId type: string message: description: Error message text examples: - expected string to match 'uuid' format type: string value: description: The value at the given location examples: - not-a-uuid type: object FilterCondition: properties: between: description: Inclusive lower and upper bounds for a range match. examples: - - 100 - 1000 items: {} type: - array - 'null' eq: description: Values matched for equality; multiple values are combined with OR. examples: - - active - pending items: {} type: - array - 'null' gt: description: Single lower-bound value that the field must exceed. examples: - - 100 items: {} type: - array - 'null' gte: description: Single inclusive lower-bound value for the field. examples: - - '2025-06-01' items: {} type: - array - 'null' in: description: Values for which the field may match any member of the list. examples: - - active - pending - suspended items: {} type: - array - 'null' lt: description: Single upper-bound value that the field must remain below. examples: - - 1000 items: {} type: - array - 'null' lte: description: Single inclusive upper-bound value for the field. examples: - - '2025-06-30' items: {} type: - array - 'null' nin: description: Values excluded from matching records. examples: - - deleted - archived items: {} type: - array - 'null' type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````