> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys.

# List Report Runs



## OpenAPI

````yaml /api-reference/reporting-api/openapi.yaml get /v2/reporting/runs
openapi: 3.1.0
info:
  title: Reporting API
  version: 0.1.0
servers:
  - url: https://api.goshippo.com
security: []
paths:
  /v2/reporting/runs:
    get:
      tags:
        - Report Runs
      summary: List Report Runs
      operationId: list_report_runs
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            description: Maximum recent runs to return.
            default: 50
            title: Limit
          description: Maximum recent runs to return.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRunListResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                  - detail
              example:
                detail: Authentication credentials were not provided.
        '422':
          description: Validation error
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
              example:
                type: https://reporthub.shippo.com/errors/validation-error
                title: Validation Error
                status: 422
                detail: The request is invalid.
      security:
        - ShippoTokenAuth: []
components:
  schemas:
    ReportRunListResponse:
      properties:
        items:
          items:
            oneOf:
              - $ref: '#/components/schemas/AcceptedReportRunResponse'
              - $ref: '#/components/schemas/RunningReportRunResponse'
              - $ref: '#/components/schemas/SucceededReportRunResponse'
              - $ref: '#/components/schemas/FailedReportRunResponse'
            discriminator:
              propertyName: status
              mapping:
                QUEUED:
                  $ref: '#/components/schemas/AcceptedReportRunResponse'
                FAILED:
                  $ref: '#/components/schemas/FailedReportRunResponse'
                PROCESSING:
                  $ref: '#/components/schemas/RunningReportRunResponse'
                SUCCEEDED:
                  $ref: '#/components/schemas/SucceededReportRunResponse'
          type: array
          title: Items
      type: object
      required:
        - items
      title: ReportRunListResponse
      description: List of report runs.
    AcceptedReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: QUEUED
          title: Status
      type: object
      required:
        - id
        - report_type
        - interval
        - columns
        - output_format
        - created
        - status
      title: AcceptedReportRunResponse
      description: Run resource while queued for processing.
    RunningReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: PROCESSING
          title: Status
      type: object
      required:
        - id
        - report_type
        - interval
        - columns
        - output_format
        - created
        - status
      title: RunningReportRunResponse
      description: Run resource while processing is in progress.
    SucceededReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: SUCCEEDED
          title: Status
        completed:
          type: integer
          title: Completed
        result:
          $ref: '#/components/schemas/ReportRunResult'
      type: object
      required:
        - id
        - report_type
        - interval
        - columns
        - output_format
        - created
        - status
        - completed
        - result
      title: SucceededReportRunResponse
      description: Terminal run resource after successful completion.
    FailedReportRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        report_type:
          type: string
          title: Report Type
        interval:
          $ref: '#/components/schemas/ReportRunInterval'
        columns:
          items:
            type: string
          type: array
          title: Columns
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        created:
          type: integer
          title: Created
        status:
          type: string
          const: FAILED
          title: Status
        completed:
          type: integer
          title: Completed
        error:
          $ref: '#/components/schemas/ReportRunError'
      type: object
      required:
        - id
        - report_type
        - interval
        - columns
        - output_format
        - created
        - status
        - completed
        - error
      title: FailedReportRunResponse
      description: Terminal run resource after an unsuccessful run.
    ReportRunInterval:
      properties:
        start:
          type: integer
          title: Start
          example: 1704067200
        end:
          type: integer
          title: End
          example: 1706745600
      type: object
      required:
        - start
        - end
      title: ReportRunInterval
      description: Report interval in UTC epoch seconds.
    OutputFormat:
      type: string
      enum:
        - csv
        - csv_gzip
        - parquet
      title: OutputFormat
      description: File format for the generated report.
    ReportRunResult:
      properties:
        row_count:
          type: integer
          title: Row Count
        size_bytes:
          type: integer
          title: Size Bytes
        download:
          oneOf:
            - $ref: '#/components/schemas/ReportRunDownloadAvailable'
            - $ref: '#/components/schemas/ReportRunDownloadUnavailable'
          title: Download
          discriminator:
            propertyName: status
            mapping:
              available:
                $ref: '#/components/schemas/ReportRunDownloadAvailable'
              unavailable:
                $ref: '#/components/schemas/ReportRunDownloadUnavailable'
      type: object
      required:
        - row_count
        - size_bytes
        - download
      title: ReportRunResult
      description: Successful run result and download state.
    ReportRunError:
      properties:
        code:
          $ref: '#/components/schemas/PublicRunErrorCode'
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ReportRunError
      description: Error details for an unsuccessful report run.
    ReportRunDownloadAvailable:
      properties:
        status:
          type: string
          const: available
          title: Status
        url:
          type: string
          title: Url
          description: A time-limited signed download URL for the generated report file.
        expires:
          type: integer
          title: Expires
          description: UTC epoch second after which the download URL expires.
      type: object
      required:
        - status
        - url
        - expires
      title: ReportRunDownloadAvailable
      description: Download state when a URL is available for the completed report.
    ReportRunDownloadUnavailable:
      properties:
        status:
          type: string
          const: unavailable
          title: Status
      type: object
      required:
        - status
      title: ReportRunDownloadUnavailable
      description: Download state when a report file is not available.
    PublicRunErrorCode:
      type: string
      enum:
        - invalid_run_request
        - run_failed
        - run_processing_failed
        - run_timeout
        - service_unavailable
      title: PublicRunErrorCode
      description: Stable error codes for failed report runs.
  securitySchemes:
    ShippoTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Shippo API token header, for example `ShippoToken shippo_live_xxxx`.

````

## Related topics

- [Create and poll a report run](/reporting-api/create-and-poll.md)
- [Discover available reports](/reporting-api/discover-reports.md)
- [Get Report Run](/api-reference/report-runs/get-report-run.md)