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

# Get Reports

> Unified convenience route (#4975) that consolidates the three singular report routes. Dispatches to the exact per-granularity cap (daily 50, weekly 100, monthly 200) and date window the legacy /api/v1/reports/{daily,weekly,monthly} routes use, so the response body is byte-identical to the matching legacy route for the same period. The three legacy routes stay live. Also reachable via the MCP get_report selector.

One route for every report granularity. Pass `granularity` (`daily`, `weekly`, or `monthly`) and the matching `period` token, and the response is byte-identical to the legacy `/api/v1/reports/{daily,weekly,monthly}` route for the same window.

The `period` token shape depends on the granularity:

* `daily`: a UTC date, `YYYY-MM-DD`.
* `weekly`: an ISO week `YYYY-WW`, or a `from,to` pair of `YYYY-MM-DD` dates.
* `monthly`: a calendar month, `YYYY-MM`.

```bash theme={null}
curl -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  "https://api.0xinsider.com/api/v1/reports?granularity=daily&period=2026-05-08"
```

The per-granularity caps match the legacy routes (daily 50, weekly 100, monthly 200), and the three legacy routes stay live. Snapshots carry trust metadata, so partial or unavailable sections are explicit. The singular [Daily](/api-reference/endpoint/get-daily-report-snapshot), [Weekly](/api-reference/endpoint/get-weekly-report-snapshot), and [Monthly](/api-reference/endpoint/get-monthly-report-snapshot) routes return the same bodies.


## OpenAPI

````yaml GET /api/v1/reports
openapi: 3.1.0
info:
  title: 0xinsider API
  description: >-
    Find your edge on Polymarket and Kalshi. Every wallet graded, every trade
    scored, every outlier flagged. API exposes trader grades, whale trades,
    smart money signals, and insider detection for AI agents, trading bots, and
    research tools. Normal API requests use a 30-second server timeout that
    returns HTTP 408 Request Timeout with an empty body when exceeded. Public
    REST /api/v1/* endpoints, excluding /api/v1/mcp, use Bearer-token based
    non-credentialed browser CORS: any Origin may call with Authorization,
    Content-Type, If-None-Match, Idempotency-Key, and Mcp-Session-Id request
    headers. Remote MCP at /api/v1/mcp is non-credentialed, but still validates
    Origin against the 0xinsider/localhost allowlist per MCP Streamable HTTP
    DNS-rebinding guidance. Successful browser CORS preflight responses
    advertise Access-Control-Max-Age: 86400. Browser JavaScript may read
    X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After,
    ETag, X-Request-Id, X-Request-Cost, X-Batch-RateLimit-Limit,
    X-Batch-RateLimit-Remaining, X-Batch-RateLimit-Reset, Mcp-Session-Id, and
    X-Mcp-Error-Code response headers. Credentialed first-party routes such as
    /api/keys, /api/billing, and auth endpoints remain restricted to configured
    0xinsider origins.
  version: 1.0.0
  contact:
    name: 0xinsider
    email: support@0xinsider.com
    url: https://0xinsider.com
servers:
  - url: https://api.0xinsider.com
    description: >-
      Production (live data). Authenticate with a live key (oxi_sk_live_...);
      requires an active Insider subscription.
  - url: https://api.0xinsider.com
    description: >-
      Sandbox / test mode (deterministic fixture data, no live rows).
      Authenticate with a test key (oxi_sk_test_...) on a free account. Same
      base URL and paths as production: the key class selects live vs sandbox.
      Test keys are billing-exempt, served from a fixed fixture dataset, and
      never read live data or persist writes; webhooks, usage, and MCP responses
      show the response shape only.
security:
  - bearerAuth: []
tags:
  - name: Traders
    description: Trader intelligence, batch lookups, timelines, and export readiness.
  - name: Positions
    description: Current prediction-market position snapshots from backend-owned mirrors.
  - name: Large Positions
    description: Largest current open positions from graded traders (Polymarket-only).
  - name: Whale Trades
    description: Recent and historical large trade intelligence.
  - name: Leaderboard
    description: Ranked trader discovery and category/strategy leaderboards.
  - name: Markets
    description: Market search, discovery, snapshots, and smart-score flow.
  - name: Insider Radar
    description: Suspicious trading pattern detection.
  - name: Events
    description: Durable public event replay streams.
  - name: Streaming
    description: Resumable real-time Server-Sent Events stream of live feed envelopes.
  - name: Webhooks
    description: Signed builder webhook destinations and delivery controls.
  - name: Usage
    description: Developer API budget and usage introspection.
  - name: System
    description: Health and operational status checks.
  - name: MCP
    description: Remote Model Context Protocol transport.
  - name: Reports
    description: Daily, weekly, monthly, and trader export report snapshots.
paths:
  /api/v1/reports:
    get:
      tags:
        - Reports
      summary: Unified report snapshot (granularity selector)
      description: >-
        Unified convenience route (#4975) that consolidates the three singular
        report routes. Dispatches to the exact per-granularity cap (daily 50,
        weekly 100, monthly 200) and date window the legacy
        /api/v1/reports/{daily,weekly,monthly} routes use, so the response body
        is byte-identical to the matching legacy route for the same period. The
        three legacy routes stay live. Also reachable via the MCP get_report
        selector.
      operationId: getReports
      parameters:
        - name: granularity
          in: query
          required: true
          description: Report granularity selector.
          schema:
            type: string
            enum:
              - daily
              - weekly
              - monthly
        - name: period
          in: query
          required: true
          description: >-
            Period token for the granularity. daily: UTC date YYYY-MM-DD.
            weekly: ISO week YYYY-WW, or a from,to YYYY-MM-DD pair. monthly: UTC
            month YYYY-MM.
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Daily report snapshot
          content:
            application/json:
              schema:
                type: object
                required:
                  - object
                  - data
                  - meta
                properties:
                  object:
                    type: string
                    const: report_snapshot
                  data:
                    $ref: '#/components/schemas/ReportSnapshot'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                success:
                  summary: Successful response
                  value:
                    object: list
                    data: []
                    has_more: false
                    next_cursor: null
                    total: 0
                    meta:
                      request_id: req_example
                      cached: false
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/SubscriptionRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/RateLimitUnavailable'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -sS \
              -H 'Authorization: Bearer $OXI_SK' \
              'https://api.0xinsider.com/api/v1/reports?granularity=daily&period=2026-02-17'
components:
  schemas:
    ReportSnapshot:
      type: object
      required:
        - kind
        - generated_at
        - source_range
        - snapshot
        - completeness
        - reconciliation
        - report
      properties:
        kind:
          type: string
          enum:
            - daily
            - weekly
            - monthly
        generated_at:
          type: string
          format: date-time
        source_range:
          $ref: '#/components/schemas/ReportSourceRange'
        snapshot:
          $ref: '#/components/schemas/SnapshotState'
        completeness:
          $ref: '#/components/schemas/SnapshotCompleteness'
        reconciliation:
          $ref: '#/components/schemas/ReportReconciliation'
        report:
          $ref: '#/components/schemas/ReportPayload'
    ResponseMeta:
      type: object
      required:
        - request_id
        - cached
      properties:
        request_id:
          type: string
          description: Unique request ID (req_ prefix).
        cached:
          type: boolean
        cache_age_s:
          type: integer
          nullable: true
          description: Cache age in seconds, null if not cached.
    ReportSourceRange:
      type: object
      required:
        - start_date
        - end_date
        - timezone
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        timezone:
          type: string
          const: UTC
    SnapshotState:
      type: object
      required:
        - status
        - generated_at
      properties:
        status:
          type: string
          enum:
            - final
            - rolling
        generated_at:
          type: string
          format: date-time
        mutable_until:
          type: string
          format: date
          nullable: true
    SnapshotCompleteness:
      type: object
      required:
        - status
        - reason
        - expected_days
        - covered_days_with_whale_activity
      properties:
        status:
          type: string
          enum:
            - complete
            - partial
            - empty
        reason:
          type: string
        expected_days:
          type: integer
        covered_days_with_whale_activity:
          type: integer
    ReportReconciliation:
      type: object
      required:
        - volume_kind
        - whale_volume_source
        - notes
      properties:
        volume_kind:
          type: string
          const: local_whale_activity_volume
        whale_volume_source:
          type: string
          const: whale_alerts.usdc_notional_num
        notes:
          type: string
    ReportPayload:
      type: object
      properties:
        total_whale_trades:
          type: integer
          nullable: true
        total_whale_volume:
          type: number
          nullable: true
        biggest_trade_size:
          type: number
          nullable: true
        active_traders:
          type: integer
          nullable: true
        top_whale_trades:
          type: array
          items:
            type: object
          nullable: true
        categories:
          type: array
          items:
            type: object
          nullable: true
        grade_distribution:
          type: array
          items:
            type: object
          nullable: true
    ApiError:
      type: object
      required:
        - object
        - error
        - meta
      properties:
        object:
          type: string
          const: error
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - bad_request
                - invalid_api_key
                - subscription_required
                - forbidden
                - not_found
                - account_locked
                - rate_limited
                - rate_limit_unavailable
                - internal_error
            message:
              type: string
            doc_url:
              type: string
              nullable: true
            param:
              type: string
              nullable: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
  headers:
    X-RateLimit-Limit:
      description: Authenticated V1 per-user request limit for the current sliding window.
      schema:
        type: integer
        example: 100
    X-RateLimit-Remaining:
      description: >-
        Authenticated V1 requests remaining in the current sliding window after
        this response.
      schema:
        type: integer
        example: 84
    X-RateLimit-Reset:
      description: Unix timestamp when the authenticated V1 request window resets.
      schema:
        type: integer
        example: 1710772860
    X-Request-Id:
      description: Server-generated request identifier for support and tracing.
      schema:
        type: string
        example: req_550e8400
  responses:
    BadRequest:
      description: Invalid request parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    SubscriptionRequired:
      description: Active Insider subscription required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Account access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RequestTimeout:
      description: >-
        Request exceeded the server's 30-second transport timeout. The timeout
        response has an empty body because it is generated before handler-level
        JSON error shaping.
    Locked:
      description: Account is locked
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: >-
        Rate limit exceeded (100 req/min; batch endpoints also reserve 100 batch
        item units/min before execution)
      headers:
        Retry-After:
          description: Seconds until rate limit resets.
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
        X-Request-Id:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimitUnavailable:
      description: >-
        Redis-backed authenticated rate limiter unavailable; retry after the
        per-process outage cooldown
      headers:
        Retry-After:
          description: >-
            Seconds until the middleware will probe the Redis-backed rate
            limiter again.
          schema:
            type: integer
        X-Request-Id:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key: Authorization: Bearer oxi_sk_live_... for live data (requires
        an active Insider subscription), or oxi_sk_test_... for sandbox/test
        mode (free account, deterministic fixture data, no live rows). Both key
        classes use the same paths; the prefix selects live vs sandbox.

````