--- title: "Published model insights and weekly statistics (beta)" method: GET path: "/models/insights" tags: ["Models"] --- # Published model insights and weekly statistics (beta) `GET /models/insights` ## Request - Base URL: `https://api.fal.ai/v1` - URL: `https://api.fal.ai/v1/models/insights` - Auth: API key in header `Authorization` Experimental (beta): model guidance and evidence may change as we refine recommendations. Find model guidance by task or endpoint. Only current public models visible to the caller are returned. Version 3 evidence includes p50/p90 in milliseconds, analytics category trending rank and registry publication dates. Statistics are optional, dated observations, not prices or quality benchmarks. Use get_pricing for current prices with their units and required configuration. **Required permissions:** none. Any authenticated caller can use this API. ## Query parameters - `endpoint_id` union: Model endpoint IDs to inspect. Repeat the parameter for multiple models; provide endpoint_id or q. - string - string[] - `q` string: Task description used to search published model guidance; provide q or endpoint_id. - `limit` integer: Maximum number of account-visible models to return. ## Response `200` Model insights - object - `evidence` object, required: Version 3 evidence for account-visible models. Weekly windows are execution measurements; trending carries its own source date. Missing evidence stays null. - `version` 3, required: Version of the model evidence contract. - `compiled_at` string, nullable, required: UTC time when the weekly snapshot was compiled, or null when no valid snapshot is available. - `window_start` string, nullable, required: Inclusive UTC start of the execution and adoption measurement week, or null when unavailable. - `window_end` string, nullable, required: Exclusive UTC end of the execution and adoption measurement week, or null when unavailable. - `evaluated_at` string, required: UTC time when newness and trending freshness were evaluated for this response. - `latency_definition` string, required: Execution measurement definition and limitations: mixed workloads, excluding queue/startup, with no runtime guarantee. - `instructions` string, required: How to interpret observations, unknowns, trending, adoption, newness and authored guidance; use the pricing tool for current prices. - `models` object[], required: Evidence for the selected current public models visible to this caller. - `endpoint_id` string, required: Current public model endpoint identifier visible to this caller. - `evidence` object, nullable, required: Weekly evidence for this model, or null when the snapshot is unavailable or the current model category does not match. - `endpoint_id` string, required: Model endpoint identifier recorded in the weekly snapshot. - `title` string, required: Model title recorded in the weekly snapshot. - `category` string, required: Catalog category used for adoption tiers and analytics trending rank. - `usage_tier` 'high' | 'medium' | 'low', nullable, required: Coarse category-relative adoption tier, or null for insufficient evidence. No raw counts are exposed; this is not trending or quality. - `latency` object, required: Observed execution latency across mixed workloads, excluding queue/startup; not a benchmark or runtime guarantee. - `p50_ms` number, nullable, required: Observed successful execution p50 in milliseconds over window_start to window_end, or null for missing or insufficient measurements. - `p90_ms` number, nullable, required: Observed successful execution p90 in milliseconds over window_start to window_end, or null for missing or insufficient measurements. - `sufficient_evidence` boolean, required: Whether at least 30 successful execution samples, 10 distinct callers and both percentiles were available; not a confidence interval or runtime guarantee. - `latest_request_at` string, nullable, required: Latest observed request end time in UTC for this endpoint within the measurement week, or null when missing; not proof of source completeness. - `trending` object, nullable, required: Category trending evidence from the existing analytics model, or null when missing, category-mismatched, future-dated or more than seven days old at evaluated_at. - `category_rank` number, required: Existing analytics model's rank within this category; separate from adoption tiers and authored recommendation order. - `computed_at` string, required: UTC source timestamp when analytics computed the trending rank, independent of the weekly execution window. - `published_at` string, nullable, required: Registry publication time in UTC recorded in the snapshot, or null when unknown; not first usage. - `is_new` boolean, nullable, required: Whether registry publication is within the inclusive 30 days ending at evaluated_at. Future publication is false; unknown publication is null. - `models` object[], required: Current public models visible to the authenticated caller. - `endpoint_id` string, required: Public model endpoint identifier. - `display_name` string, required: Current public model display name. - `category` string, required: Catalog category used for within-category tier comparisons. - `relevance` number, nullable, required: Search relevance score, or null without a search match; not a quality score. - `insights` object[], required: Published guidance for this model; may be empty. - `kind` string, required: Guidance kind, such as a strength, limitation, or default pick. - `body` string, required: Published guidance text for the model. - `source` string, required: Whether the published guidance was curated or learned. - `task` object, nullable, required: Associated task, or null for general model guidance. - `name` string, required: Name of the task associated with this guidance. - `category` string, nullable, required: Task's catalog category, or null when unspecified. - `rank` number, nullable, required: Published recommendation order for this guidance, or null when unranked. - `unavailable_endpoint_ids` string[], required: Explicitly requested endpoint IDs that are not public or accessible to this caller. - `stats_available` boolean, required: Whether a valid snapshot for the last completed week was available; individual model evidence may still be unknown. - `note` string, required: Guidance on interpreting observations, trending, adoption, newness and recommendations. ## Other responses - `400`: Invalid request parameters - `401`: Authentication required - `404`: Resource not found - `429`: Rate limit exceeded - `500`: Internal server error ## Changes - **2026-09-17** `ef822ef3501d`: 1 breaking, 1 info - removed the required property `models/items/stats` from the response with the `200` status - added the required property `evidence` to the response with the `200` status - **2026-09-16** `04f815c7612b`: 1 info - endpoint added [Operation history](https://skmtc.dev/fal/apis/platform-apis/changes/models/insights/get.md) --- [API](https://skmtc.dev/fal/apis/platform-apis.md) - [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/fal/apis/platform-apis/revisions/3b3b61bedf06?raw)