Fillo Insights API

openapi: 3.2.0
info:
  title: Fillo So Insights API
  version: 1.0.0
  contact:
    name: Fillo support
    email: hello@fillo.so
    url: https://fillo.so/developers
  description: 'Operations tagged Insights across 2 of this provider''s published API definitions: fillo-so-openapi.json, fillo-so-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fillo.so
security:
- bearerAuth: []
tags:
- name: Insights
paths:
  /api/v1/manage/forms/{form}/insights:
    get:
      tags:
      - Insights
      summary: Get a form's insights
      operationId: getFormInsights
      description: 'The numbers the dashboard''s Insights page shows, from the same core: totals, median completion time, seven-day change, the daily timeline, source and surface breakdowns, the drop-off funnel, open drafts, and every question''s distribution. Filters use the same grammar as the responses list, so the numbers and the rows always describe the same set. Accepted responses only. Every question''s distribution quotes respondent answers verbatim as labels, so this is a response read wearing an analytics shape: it needs forms:read AND responses:read, the second asserted after authentication and named in its own 403.'
      parameters:
      - $ref: '#/components/parameters/FormHandle'
      - name: range
        in: query
        description: 'Date window: 7d, 30d, 90d, or all (default).'
        schema:
          type: string
          enum:
          - 7d
          - 30d
          - 90d
          - all
      - name: q
        in: query
        description: Free-text search across answers and source.
        schema:
          type: string
      - name: source
        in: query
        description: Match the submission source (host + path).
        schema:
          type: string
      - name: respondent
        in: query
        description: Exact identify() external id.
        schema:
          type: string
      - name: where
        in: query
        description: Field filter as `fieldId:op:value`, repeatable, max 20. op is one of eq, neq, contains, gt, lt, answered, not_answered.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: by
        in: query
        description: Compare the cohort that answered this field against the baseline.
        schema:
          type: string
      - name: op
        in: query
        description: How `by` matches. Default eq.
        schema:
          type: string
          enum:
          - eq
          - answered
          - not_answered
      - name: eq
        in: query
        description: The value `by` must equal when op is eq.
        schema:
          type: string
      responses:
        '200':
          description: The form's insights for the requested window and filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormInsights'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
components:
  responses:
    NotFound:
      description: No such resource in this project (returned instead of 403 for ids in other projects).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key (120/min), per-workspace (240/min), or per-IP (300/min) rate limit exceeded. Retry after the Retry-After header.
      headers:
        RateLimit-Policy:
          description: Named quota policies and their limits/windows.
          schema:
            type: string
        RateLimit:
          description: Current remaining quota and seconds until reset for each named policy.
          schema:
            type: string
        RateLimit-Limit:
          description: 'Compatibility field: effective request limit.'
          schema:
            type: integer
        RateLimit-Remaining:
          description: 'Compatibility field: effective requests remaining.'
          schema:
            type: integer
        RateLimit-Reset:
          description: 'Compatibility field: seconds until the effective window resets.'
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, unknown, revoked, or expired key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request (e.g. a body on a GET/DELETE, or a missing required query parameter).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    FormInsights:
      type: object
      required:
      - range
      - total
      - timeline
      - sources
      - surfaces
      - fields
      properties:
        range:
          type: string
          enum:
          - 7d
          - 30d
          - 90d
          - all
        total:
          type: integer
        firstAt:
          type:
          - integer
          - 'null'
        lastAt:
          type:
          - integer
          - 'null'
        medianDurationMs:
          type:
          - integer
          - 'null'
        durationCount:
          type: integer
        lastSevenDays:
          type: integer
        previousSevenDays:
          type: integer
        sevenDayChange:
          type:
          - number
          - 'null'
        sampled:
          type: boolean
        versionCount:
          type: integer
        legacyHistoryIncomplete:
          type: boolean
        timeline:
          type: array
          items:
            type: object
            required:
            - day
            - count
            properties:
              day:
                type: string
              count:
                type: integer
        sources:
          type: array
          items:
            $ref: '#/components/schemas/InsightBreakdownRow'
        surfaces:
          type: array
          items:
            $ref: '#/components/schemas/InsightBreakdownRow'
        funnel:
          type:
          - object
          - 'null'
          description: started, completed, excluded, completionRate, multiPage, and a per-page reached/pct list.
        drafts:
          type:
          - object
          - 'null'
          description: open, identified, and byPage — the same counts the drafts endpoint returns.
        fields:
          type: array
          description: 'One entry per field ever answered: id, label, kind, inCurrentSchema, answered, skipped, fillRate, and a `summary` discriminated on `type` (choice, multi, ranking, scale, number, boolean, matrix, text, date, file, generic).'
          items:
            type: object
        segment:
          type:
          - object
          - 'null'
          description: 'Present when `by` is supplied: the cohort''s size, share, its own `fields`, and the `differences` that separate it from the baseline.'
        segmentIgnored:
          type: boolean
          description: True when `by` named a field the current data cannot segment on.
      description: The same computation the dashboard's Insights page renders. Epoch-millisecond timestamps.
    InsightBreakdownRow:
      type: object
      required:
      - key
      - label
      - count
      - pct
      properties:
        key:
          type: string
        label:
          type: string
        count:
          type: integer
        pct:
          type: number
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  parameters:
    FormHandle:
      name: form
      in: path
      required: true
      description: A form id or slug.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A project secret key (`fsk_…`). Scopes: forms:read, responses:read, respondents:read, responses:export, forms:write, forms:publish, storage:manage, webhooks:manage, settings:manage, integrations:manage, responses:manage, members:manage, workspace:manage, forms:delete, responses:delete, respondents:delete, workspace:delete. A request for a scope the key lacks returns 403 with a stable message naming the scope (e.g. `This key lacks the responses:export scope.`).'
externalDocs:
  description: Fillo developer resources
  url: https://fillo.so/developers
x-refined-from:
- fillo-so-openapi.json
- fillo-so-openapi.json
x-provenance:
  method: harvested
  publisher: Fillo
  source: https://fillo.so/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)