> ## Documentation Index > Fetch the complete documentation index at: https://docs.avidoai.com/llms.txt > Use this file to discover all available pages before exploring further. # List reports > Retrieves a paginated list of reports with optional filtering by date range, assignee, and application. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/avido/openapi.documented.yml get /v0/reporting openapi: 3.1.1 info: title: Avido API description: >- Avido's API for LLM usage events, tool calls, trace management, webhook validation, and more. See each endpoint's request/response schema for details. version: 0.1.0 contact: name: Avido Support email: support@avidoai.com url: https://avidoai.com/support servers: - url: https://api.avidoai.com description: Production API security: - ApiKey: [] ApplicationId: [] paths: /v0/reporting: get: tags: - Reports summary: List reports description: >- Retrieves a paginated list of reports with optional filtering by date range, assignee, and application. operationId: listReports parameters: - in: query name: skip schema: description: Number of items to skip before starting to collect the result set. example: 0 default: 0 type: integer minimum: 0 maximum: 9007199254740991 description: Number of items to skip before starting to collect the result set. - in: query name: limit schema: description: Number of items to include in the result set. example: 25 type: integer minimum: 1 maximum: 100 description: Number of items to include in the result set. - in: query name: orderBy schema: description: Field to order the result set by. example: createdAt default: createdAt type: string enum: - createdAt - modifiedAt - title - assignee - id description: Field to order the result set by. - in: query name: orderDir schema: description: Order direction. example: desc default: desc type: string enum: - asc - desc description: Order direction. - in: query name: assignee schema: description: Filter by assignee user ID example: user_789012 type: string description: Filter by assignee user ID - in: query name: start schema: description: Start date (ISO8601) for filtering reports by creation date example: '2025-01-01T00:00:00Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Start date (ISO8601) for filtering reports by creation date - in: query name: end schema: description: End date (ISO8601) for filtering reports by creation date example: '2025-01-31T23:59:59Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: End date (ISO8601) for filtering reports by creation date responses: '200': description: Successfully retrieved reports content: application/json: schema: $ref: '#/components/schemas/PaginatedReportResponse' examples: success: summary: List of reports value: data: - id: 123e4567-e89b-12d3-a456-426614174000 orgId: org_123456 applicationId: 456e7890-e89b-12d3-a456-426614174000 title: Monthly Performance Report description: >- Comprehensive analysis of AI model performance for December 2024 assignee: user_789012 createdAt: '2024-01-05T12:34:56.789Z' modifiedAt: '2024-01-05T12:34:56.789Z' pagination: skip: 0 limit: 25 total: 1 totalPages: 1 empty: summary: No reports found value: data: [] pagination: skip: 0 limit: 25 total: 0 totalPages: 0 '400': description: bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: invalid input content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '500': description: internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PaginatedReportResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ReportOutput' pagination: type: object properties: skip: type: integer minimum: 0 maximum: 9007199254740991 description: Number of items skipped. example: 0 limit: type: integer minimum: 1 maximum: 9007199254740991 description: Number of items per page. example: 25 total: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of items available. example: 100 totalPages: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of pages available. example: 4 totalCount: description: >- Total number of items without filters applied. Used to distinguish between truly empty results and empty filtered results. example: 100 type: integer minimum: 0 maximum: 9007199254740991 required: - skip - limit - total - totalPages additionalProperties: false title: PaginationResponse description: Pagination metadata returned in a paginated response. required: - data - pagination additionalProperties: false title: PaginatedReportResponse description: Paginated response containing reports ErrorResponse: type: object properties: message: type: string description: A human-readable error message explaining the error. example: Resource not found required: - message additionalProperties: false title: ErrorResponse description: Standard error format for failed API operations. ValidationErrorResponse: type: object properties: message: type: string description: A human-readable error message indicating what went wrong. example: Invalid request data issues: type: array items: type: object properties: code: type: string message: type: string path: type: array items: type: string required: - code - message - path additionalProperties: false description: Array of detailed validation error objects. example: - code: invalid_string message: Invalid UUID path: - id required: - message - issues additionalProperties: false title: ValidationErrorResponse description: Details about validation errors in incoming requests. ReportOutput: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Unique identifier of the report example: 123e4567-e89b-12d3-a456-426614174000 orgId: type: string description: Organization ID that owns this report example: org_123456 applicationId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The application this report belongs to example: 456e7890-e89b-12d3-a456-426614174000 title: type: string description: Title of the report example: Monthly Performance Report description: type: string description: Detailed description of the report example: Comprehensive analysis of AI model performance for December 2024 assignee: description: User ID of the person assigned to this report example: user_789012 type: string query: $ref: '#/components/schemas/ReportingQueryOutput' description: >- Optional reporting query configuration defining datasource, filters, groupBy, measurements, and ordering createdAt: description: When the report was created example: '2024-01-05T12:34:56.789Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ modifiedAt: description: When the report was last modified example: '2024-01-05T12:34:56.789Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - orgId - applicationId - title - description - createdAt - modifiedAt additionalProperties: false title: Report description: A report for tracking and analyzing AI application performance ReportingQueryOutput: type: object properties: datasource: $ref: '#/components/schemas/ReportingQueryDatasource' description: Datasource to query example: task timezone: type: string description: >- IANA timezone identifier for date filter resolution (e.g., 'America/New_York', 'Europe/London', 'UTC') example: America/New_York filters: description: >- Optional filters to apply to the query. Each filter must specify a type (string/number/boolean/date) that matches the column type. example: - type: string column: type operator: eq value: - STATIC type: array items: $ref: '#/components/schemas/ReportingQueryFilterOutput' groupBy: description: >- Optional group by clauses for aggregating results. For date columns, dateTrunc is required. example: - column: type type: string - column: createdAt type: date dateTrunc: month type: array items: $ref: '#/components/schemas/ReportingQueryGroupByOutput' measurements: description: >- Optional measurements/aggregations to compute when using groupBy. Defaults to count if not specified. Use avg/sum/min/max for numeric or boolean columns. example: - type: count - type: avg column: score type: array items: $ref: '#/components/schemas/MeasurementOutput' orderBy: description: >- Optional ordering specification. If not specified, defaults to ordering by all groupBy columns (with createdAt priority) then measurements. For non-groupBy queries, defaults to createdAt DESC, id DESC. example: - column: createdAt direction: desc - column: count direction: asc type: array items: type: object properties: column: type: string description: >- Column name to order by (must be a groupBy column or measurement alias) example: createdAt direction: type: string enum: - asc - desc description: Sort order direction (ascending or descending). example: desc required: - column - direction additionalProperties: false title: ReportingQueryOrderBy description: >- Order by specification for sorting results. Column must be in the SELECT clause (groupBy column or measurement). includeArchived: description: >- When true, includes archived entities (tasks, topics, tags) in the query results. Defaults to false, which filters out archived data. example: false type: boolean required: - datasource - timezone additionalProperties: false title: ReportingQuery description: >- Reporting query definition with datasource, filters, groupBy, measurements, and ordering ReportingQueryDatasource: type: string enum: - task - test - eval - topic - tag - human_annotation ReportingQueryFilterOutput: oneOf: - $ref: '#/components/schemas/ReportingQueryStringFilterOutput' - $ref: '#/components/schemas/ReportingQueryNumberFilterOutput' - $ref: '#/components/schemas/ReportingQueryBooleanFilterOutput' - $ref: '#/components/schemas/ReportingQueryDateFilterOutput' title: ReportingQueryFilter description: >- Filter for reporting queries. Type must match the column type in the datasource. type: object discriminator: propertyName: type mapping: string: $ref: '#/components/schemas/ReportingQueryStringFilterOutput' number: $ref: '#/components/schemas/ReportingQueryNumberFilterOutput' boolean: $ref: '#/components/schemas/ReportingQueryBooleanFilterOutput' date: $ref: '#/components/schemas/ReportingQueryDateFilterOutput' ReportingQueryGroupByOutput: oneOf: - type: object properties: column: type: string description: Column name to group by (must be whitelisted for datasource) example: type type: type: string enum: - string - number - boolean description: Column type for non-date columns example: string required: - column - type additionalProperties: false title: ReportingQueryGroupByBase description: Group by specification for non-date columns - type: object properties: column: type: string description: >- Date column name to group by (must be whitelisted for datasource) example: createdAt type: type: string const: date description: Column type for date columns example: date dateTrunc: $ref: '#/components/schemas/ReportingQueryDateTrunc' description: Required date truncation granularity for date columns example: month required: - column - type - dateTrunc additionalProperties: false title: ReportingQueryGroupByDate description: Group by specification for date columns with required truncation title: ReportingQueryGroupBy description: >- Group by specification with discriminated union on type field. Date columns require dateTrunc parameter. type: object MeasurementOutput: type: object properties: type: $ref: '#/components/schemas/MeasurementType' description: Type of measurement to perform example: avg column: description: Column to measure (required for avg/sum/min/max, not used for count) example: score type: string alias: description: >- Optional alias for the measurement in results (defaults to type_column or 'count') example: average_score type: string required: - type additionalProperties: false title: Measurement description: >- Measurement/aggregation specification for GROUP BY queries. Count measures all records, while avg/sum/min/max measure specific numeric/boolean columns. ReportingQueryStringFilterOutput: type: object properties: type: type: string const: string description: Filter type for string columns column: type: string description: Column name to filter on (must be a string column in the datasource) example: type operator: type: string enum: - eq - neq description: Filter operator for string values example: eq value: minItems: 1 type: array items: type: string description: Array of string values to filter by example: - STATIC - NORMAL required: - type - column - operator - value additionalProperties: false title: ReportingQueryStringFilter description: Filter for string columns using eq/neq operators ReportingQueryNumberFilterOutput: type: object properties: type: type: string const: number description: Filter type for numeric columns column: type: string description: >- Column name to filter on (must be a numeric column in the datasource) example: score operator: type: string enum: - eq - neq - lt - gt - lte - gte description: Filter operator for numeric values example: gte value: minItems: 1 type: array items: type: number description: >- Array of numeric values to filter by (for comparison operators, only first value is used) example: - 0.8 required: - type - column - operator - value additionalProperties: false title: ReportingQueryNumberFilter description: Filter for numeric columns using eq/neq/lt/gt/lte/gte operators ReportingQueryBooleanFilterOutput: type: object properties: type: type: string const: boolean description: Filter type for boolean columns column: type: string description: >- Column name to filter on (must be a boolean column in the datasource) example: passed operator: type: string enum: - eq description: Filter operator for boolean values example: eq value: type: boolean description: Boolean value to filter by example: true required: - type - column - operator - value additionalProperties: false title: ReportingQueryBooleanFilter description: Filter for boolean columns using eq operator with single value ReportingQueryDateFilterOutput: type: object properties: type: type: string const: date description: Filter type for date columns column: type: string description: Column name to filter on (must be a date column in the datasource) example: createdAt dateFilter: $ref: '#/components/schemas/DateFilterOutput' description: >- Date filter supporting absolute ranges, presets, and relative windows required: - type - column - dateFilter additionalProperties: false title: ReportingQueryDateFilter description: Filter for date columns using date filter (range/preset/relative) ReportingQueryDateTrunc: type: string enum: - year - month - week - day - hour description: >- Date truncation granularity for grouping date columns using PostgreSQL date_trunc MeasurementType: type: string enum: - count - avg - sum - min - max description: >- Type of measurement/aggregation to perform. count works on all columns, while avg/sum/min/max require numeric or boolean columns. DateFilterOutput: oneOf: - $ref: '#/components/schemas/DateFilterRangeOutput' - $ref: '#/components/schemas/DateFilterPresetOutput' - $ref: '#/components/schemas/DateFilterRelativeOutput' title: DateFilter description: >- Date filter supporting absolute ranges, presets (thisQuarter, last30Days), and relative windows (last N days/weeks/months) type: object discriminator: propertyName: type mapping: range: $ref: '#/components/schemas/DateFilterRangeOutput' preset: $ref: '#/components/schemas/DateFilterPresetOutput' relative: $ref: '#/components/schemas/DateFilterRelativeOutput' DateFilterRangeOutput: type: object properties: type: type: string const: range description: Absolute date range with explicit boundaries from: description: Inclusive start boundary (ISO8601). Omit for open-ended range. example: '2025-01-01T00:00:00Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ to: description: Exclusive end boundary (ISO8601). Omit for open-ended range. example: '2025-02-01T00:00:00Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - type additionalProperties: false title: DateFilterRange description: >- Absolute date range with optional from/to boundaries. from is inclusive, to is exclusive. DateFilterPresetOutput: type: object properties: type: type: string const: preset description: Preset date range using common shortcuts preset: $ref: '#/components/schemas/DateFilterPresetValue' required: - type - preset additionalProperties: false title: DateFilterPreset description: >- Preset date range that expands to concrete dates at query time (e.g., thisQuarter, last30Days) DateFilterRelativeOutput: type: object properties: type: type: string const: relative description: Relative date range using offsets from now unit: $ref: '#/components/schemas/DateFilterUnit' from: type: integer minimum: 0 maximum: 9007199254740991 description: >- Starting offset (units ago from now). 0 = now. Must be < to. Defaults to 0. example: 0 to: type: integer minimum: 1 maximum: 9007199254740991 description: Ending offset (units ago from now). Must be > from. Defaults to 1. example: 14 required: - type - unit - from - to additionalProperties: false title: DateFilterRelative description: >- Relative date range using bounded offsets from now (e.g., last 14 days, 2-6 weeks ago) DateFilterPresetValue: type: string enum: - today - yesterday - last_7_days - last_30_days - last_90_days - last_12_months - this_week - last_week - this_month - last_month - this_quarter - last_quarter - this_year - last_year description: Preset date range that expands to concrete dates at query time example: last_30_days DateFilterUnit: type: string enum: - day - week - month - quarter - year description: Time unit for relative date ranges (day, week, month, quarter, year) example: day securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: Your unique Avido API key ApplicationId: type: apiKey in: header name: x-application-id description: Your unique Avido Application ID ````