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

# Generate insight report

> Starts an insight report for one task type and date range. The report is written in the background: the response returns its `resultId` with `status: pending`; poll `GET /ai-insight/results/{id}` until it is `done` or `failed`.
The task type needs a saved context, and the range needs enough tasks (50 by default), otherwise 400 tells you how many were found. `endDate` can't be before `startDate`. Dates are read in `timezone` (an IANA name, for example `Asia/Jakarta`); an unknown or empty timezone means UTC.
Requires the `view/ai-insight` permission.



## OpenAPI

````yaml /openapi/public/openapi-analytics.json post /ai-insight/generate
openapi: 3.0.0
info:
  title: API - Analytics
  version: 3.0.0
  description: API Documentation - RESTful API for field operations management.
servers:
  - url: https://apiweb.mile.app/api/v3
security:
  - bearerAuth: []
tags:
  - name: Dashboard
    description: >-
      Dashboard lets a user compose their own dashboard from any number of
      cards, start from a template, duplicate a dashboard, share it with roles,
      and save it back as an organization template. Each card owns its own
      widget row (a chart type plus a query spec), cloned from the widget
      catalogue (built-in widgets plus the organization's custom widgets), so
      renaming or editing a card never touches the catalogue or another
      dashboard. Dashboards are owned by their creator: roles they are shared
      with can view, duplicate and save as template, but only the owner can edit
      or delete. Every write reuses the dashboard permission family (view, add,
      edit and delete dashboard).


      The numbers behind each card come from one generic aggregation endpoint
      instead of one endpoint per chart: the client sends a batch of up to 12
      declarative query specs, the server injects the caller's organization, hub
      and soft-delete scope from the session, runs each spec read-only, and
      returns a flat columns and rows table per item. The catalog endpoints
      describe the data sources, fields and limits a client may use.
  - name: Report
    description: >-
      A report is a saved table definition over tasks of one task type or
      records of one data type: which fields to show, which hubs to include, and
      the default filters.
  - name: Insight Report
    description: >-
      Insight reports are written summaries of your operations, generated from
      your task and data records: findings, a summary and suggested actions. You
      set the context once per task type, then generate reports on demand or on
      a schedule.
paths:
  /ai-insight/generate:
    post:
      tags:
        - Insight Report
      summary: Generate insight report
      description: >-
        Starts an insight report for one task type and date range. The report is
        written in the background: the response returns its `resultId` with
        `status: pending`; poll `GET /ai-insight/results/{id}` until it is
        `done` or `failed`.

        The task type needs a saved context, and the range needs enough tasks
        (50 by default), otherwise 400 tells you how many were found. `endDate`
        can't be before `startDate`. Dates are read in `timezone` (an IANA name,
        for example `Asia/Jakarta`); an unknown or empty timezone means UTC.

        Requires the `view/ai-insight` permission.
      operationId: generateInsightReport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightGenerateRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                example:
                  status: true
                  data:
                    resultId: 670fa1b2c3d4e5f6a7b8c9d0
                    status: pending
                additionalProperties: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: Shows if the request was successful.
                  message:
                    type: string
                    description: A short message explaining what went wrong.
                example:
                  status: false
                  message: Bad request - invalid parameters provided.
      deprecated: false
      security:
        - bearerAuth: []
components:
  schemas:
    InsightGenerateRequest:
      type: object
      required:
        - objectId
        - startDate
        - endDate
      properties:
        objectId:
          type: string
          description: |-
            Task type (flow) id.
            **Example:** `64ee1a2b3c4d5e6f7a8b9c0d`
        objectType:
          type: string
          enum:
            - flow
          description: |-
            Only `flow` today.
            **Default:** `flow`
        startDate:
          type: string
          description: |-
            First day, `YYYY-MM-DD`.
            **Example:** `2026-10-01`
        endDate:
          type: string
          description: |-
            Last day, `YYYY-MM-DD`.
            **Example:** `2026-10-15`
        timezone:
          type: string
          description: |-
            IANA timezone the dates are read in.
            **Default:** `UTC`
            **Example:** `Asia/Jakarta`
        name:
          type: string
          maxLength: 200
          description: |-
            Report name.
            **Example:** `Delivery, first half of October`
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use a valid Bearer token to authenticate.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.