Run an Insights segment

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.

Required scope: insights:write

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
integer
required
integer
required

Segment id

Responses

Language
Credentials
OAuth2
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json