---
title: "Run an Insights segment"
method: POST
path: "/api/v4/f/{firm_id}/segments/{id}/runs"
tags: ["Insights"]
---

# Run an Insights segment

`POST /api/v4/f/{firm_id}/segments/{id}/runs`

## Request

- Base URL: `https://live.getsilverfin.com`
- URL: `https://live.getsilverfin.com/api/v4/f/{firm_id}/segments/{id}/runs`
- Auth: OAuth 2
  - Authorization code: `https://live.getsilverfin.com/oauth/authorize`
  - Token URL: `https://live.getsilverfin.com/oauth/token` scopes: `insights:write`

Runs the segment for the authenticated user and returns immediately with a run
reference and its status; it does not wait for the segment run to finish. The
run only covers the companies the token's user can access in Silverfin, and
never changes the segment's definition.

If a run of this segment is already in progress, no new run is started. The
response describes that pending run with the pending payload documented on
`GET /segments/{id}/results`, without its `message`. Poll that endpoint
until it finishes.

If the user's latest run of the segment finished less than
12 hours ago, no new run is started either. The 200 response
describes that finished run (`status` is `finished`) and carries a `message`
and `next_run_allowed_at`, the earliest time (ISO 8601) a request can start a
new run. A request at that time can still get a 409 at the firm's limit.
Fetch the results from `GET /segments/{id}/results`. Runs started in the
Silverfin UI count as well. A change to the segment's filters or period
removes the earlier runs, so the next request starts a new run at once.

Otherwise a new execution is created (a 202): there is no run yet, or the
latest run was cancelled or finished 12 hours ago or more. The
results of that earlier run are discarded.

A firm can have a limited number of runs in progress at the same time;
further requests are rejected with a 409 until a run
finishes. Runs started from the Silverfin UI count towards that limit.
Only the firm's own segments can be run through the API; recommended
segments cannot.

This endpoint exists in API v4 only; on the deprecated v3 API it returns a 404.

This endpoint requires a user OAuth token and Insights Premium.<br>
<b>Required scope:</b> `insights:write`

## Path parameters

- `firm_id` integer, required
- `id` integer, required

## Response `200`

A run is in progress, or the latest finished run is less than 12 hours old; no new run is started and that run is described

- union
  - InsightsSegmentRunPending
    - `status` 'pending', required
    - `request_ref` string, uuid, required
    - `started_at` string, date-time, required: Run creation time, with millisecond precision
    - `finished_at` string, date-time, nullable, required: Calculation completion time, or null while pending
    - `progress` object, required
      - `processed_companies` integer, required: Companies processed so far. Informational only: a two-pass run can count a company more than once.
  - InsightsSegmentRunRecentlyFinished
    - `status` 'finished', required
    - `request_ref` string, uuid, required
    - `started_at` string, date-time, required: Run creation time, with millisecond precision
    - `finished_at` string, date-time, nullable, required: Calculation completion time, or null while pending
    - `next_run_allowed_at` string, date-time, required: The earliest time a request can start a new run: 12 hours after finished_at
    - `message` string, required

## Other responses

- `202`: A new segment run was started
- `403`: The token is an application token (a user token is required), or the firm does not have Insights Premium
- `404`: The segment does not exist, is not accessible, or is not one of the firm's own segments
- `409`: The firm already has the maximum number of segment runs in progress

## Changes

- **2026-11-03** `e418e4fc02e8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/silverfin/apis/silverfin-api/changes/api/v4/f/:firm_id/segments/:id/runs/post.md)

---

[API](https://skmtc.dev/silverfin/apis/silverfin-api.md) - [All operations](https://skmtc.dev/silverfin/apis/silverfin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/silverfin/apis/silverfin-api/revisions/e418e4fc02e8?raw)