> ## Documentation Index > Fetch the complete documentation index at: https://docs.runflow.io/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate run usage for the current org over a date range > Return timeline, top targets, and source split for one org. All aggregation runs in PostgreSQL — the response shape is bounded by the date range and a fixed top-N, not by the org's run volume. ``by_flow`` is filtered to target types whose parent resource the caller has ``read`` on (``flows:read`` / ``models:read`` / ``comfyui-workflows:read``); rows for target types the caller cannot read are dropped silently. ``timeline`` and ``by_source`` always aggregate every run in scope — they expose only counts and spend, no target identity. ## OpenAPI ````yaml /api/openapi.public.json get /v1/runs-stats openapi: 3.1.0 info: title: Runflow API version: 0.1.0 description: >- Public Runflow API. Run AI image and video models, manage media, inspect run history, and configure webhooks. Auth: HTTP Bearer. This document is the customer integration surface only. Admin and internal operations plus generic system reference-data tables are intentionally omitted. servers: - url: https://api.runflow.io description: Production security: - HTTPBearer: [] tags: - name: Models description: >- Browse the model catalog and dispatch model runs. The primary surface for running AI image and video generation. - name: Runs description: >- Inspect, cancel, and re-run model executions. Fetch logs, node-runs, and callback delivery history. - name: Media description: >- Upload images and videos as inputs. Organize assets into folders. Three-step presigned upload flow for large files. - name: Batches description: >- Run a model on multiple inputs in one request. Includes per-item status and a single callback when the batch completes. - name: Evaluations description: >- Submit an image generated anywhere for automated quality evaluation, then read a pass verdict, a 0-1 score, and structured issues. No Runflow run required. - name: Webhooks description: >- Subscribe to platform events. Inspect delivery history, redeliver failed callbacks, manage signing secrets. - name: Account description: Read your account identity and credit balance. - name: Status description: Health and readiness probes for the API. paths: /v1/runs-stats: get: tags: - Runs summary: Aggregate run usage for the current org over a date range description: |- Return timeline, top targets, and source split for one org. All aggregation runs in PostgreSQL — the response shape is bounded by the date range and a fixed top-N, not by the org's run volume. ``by_flow`` is filtered to target types whose parent resource the caller has ``read`` on (``flows:read`` / ``models:read`` / ``comfyui-workflows:read``); rows for target types the caller cannot read are dropped silently. ``timeline`` and ``by_source`` always aggregate every run in scope — they expose only counts and spend, no target identity. operationId: listRunsStats parameters: - name: start in: query required: true schema: type: string format: date-time description: Inclusive lower bound on Run.created_at (ISO-8601, UTC). title: Start description: Inclusive lower bound on Run.created_at (ISO-8601, UTC). - name: end in: query required: true schema: type: string format: date-time description: Inclusive upper bound on Run.created_at (ISO-8601, UTC). title: End description: Inclusive upper bound on Run.created_at (ISO-8601, UTC). - name: X-Organization-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Organization-Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RunStatsResponse' '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 — inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, ORGANIZATION_MEMBERSHIP_REQUIRED, ROLE_UNRESOLVED, IMPERSONATION_READ_ONLY) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] components: schemas: RunStatsResponse: properties: timeline: items: $ref: '#/components/schemas/UsageDataPoint' type: array title: Timeline by_flow: items: $ref: '#/components/schemas/UsageByFlow' type: array title: By Flow by_source: items: $ref: '#/components/schemas/UsageBySource' type: array title: By Source type: object required: - timeline - by_flow - by_source title: RunStatsResponse description: Aggregate run usage for one org over [start, end]. ErrorResponse: properties: code: type: string title: Code message: type: string title: Message errors: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Errors type: object required: - code - message title: ErrorResponse description: Standard error envelope — matches exception handler output. UsageDataPoint: properties: date: type: string format: date title: Date runs: type: integer title: Runs spend: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Spend type: object required: - date - runs - spend title: UsageDataPoint description: One UTC day in the timeline. UsageByFlow: properties: flow_slug: type: string title: Flow Slug flow_name: type: string title: Flow Name runs: type: integer title: Runs spend: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Spend avg_duration_ms: type: number title: Avg Duration Ms target_type: $ref: '#/components/schemas/RunTargetTypeCodeLiteral' type: object required: - flow_slug - flow_name - runs - spend - avg_duration_ms - target_type title: UsageByFlow description: |- Aggregate for one target (flow, model, or comfyui workflow). The field names retain the legacy ``flow_*`` prefix even when the row represents a model or comfyui target — keeps the API contract aligned with the existing frontend ``UsageByFlow`` UI type. Renaming is a future cosmetic change. ``target_type`` lets the caller distinguish branches; the ``slug`` namespace is shared across tables so it alone is not unambiguous. UsageBySource: properties: source: type: string enum: - api - playground - other title: Source runs: type: integer title: Runs pct: type: number title: Pct type: object required: - source - runs - pct title: UsageBySource description: Run count + percentage share for one source bucket. RunTargetTypeCodeLiteral: type: string enum: - model - flow - comfyui securitySchemes: HTTPBearer: type: http scheme: bearer ````