Returns the results of the authenticated user's latest run of the segment for the companies that user can access in Silverfin. This endpoint never starts a segment run.

While a run is in progress a 202 with its progress is returned; the previous run's results are never served as current. When no generated results exist (or they expired), the response will return a 404 status code. You can start a new run via POST /segments/{id}/runs.

The pending payload

While the run is in progress, the 202 response indicates current progress instead of results:

{
  "status": "pending",
  "request_ref": "9f8c0a2e-1d3b-4f5a-8c7e-2b6d4a1f0e93",
  "started_at": "2026-08-04T09:12:44.000+02:00",
  "finished_at": null,
  "progress": {
    "processed_companies": 128
  },
  "message": "The segment run is not ready yet. Poll this endpoint until it finishes."
}

POST /segments/{id}/runs answers with this same payload, without message, whenever it reports a pending run. When the latest run finished less than 12 hours ago, it answers with that finished run's status, request_ref, started_at and finished_at, plus next_run_allowed_at and a message that points to this endpoint.

The finished payload

A finished run of a segment with two columns, one client file matching:

{
  "status": "finished",
  "request_ref": "9f8c0a2e-1d3b-4f5a-8c7e-2b6d4a1f0e93",
  "started_at": "2026-08-04T09:12:44.000+02:00",
  "finished_at": "2026-08-04T09:13:07.000+02:00",
  "period_selection": {
    "type": "financial_year",
    "date": "2025-12-31"
  },
  "columns": [
    {
      "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "BookyearEnd",
      "name": "Book year end",
      "settings": {
        "comparison_mode": "exactly",
        "end_date": "2025-12-31"
      }
    },
    {
      "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "type": "Todos",
      "name": "To-dos",
      "settings": {
        "status": "open"
      }
    }
  ],
  "matches": [
    {
      "company_id": 918273,
      "company_name": "Acme NV",
      "period_id": 5544332,
      "period_end_date": "2025-12-31",
      "values": {
        "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d": {
          "formatted_value": "31/12/2025",
          "sort_value": "2025-12-31"
        },
        "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e": {
          "formatted_value": {
            "status": "partially_done",
            "completed": 3,
            "total": 7
          },
          "sort_value": 4
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 200,
    "total_matches": 128,
    "total_pages": 1
  },
  "non_match_count": 41
}

Envelope

Timestamps are ISO 8601 with the server's UTC offset (e.g. +02:00).

columns

type, name and settings are all null on the rare run column that no longer maps to one of the segment's filters.

uuid is not an identifier, and must not be treated as stable. Its only job is to tie a column to its values inside one response. It is stored with the run, so fetching the same finished run again returns the same uuids, but that is a consequence of reading one cached result twice, not a guarantee. A new run generates new ones, and the same column then comes back under a different uuid. So read columns from the same payload you read matches from and correlate through it, rather than persisting a uuid or comparing uuids across responses. columns follows the segment's filter order if you need to recognise a column from one run to the next; type repeats when a segment has two columns of the same kind, and name follows the run user's language.

columns.settings

Each columns item contains settings, which carries the filter's configuration as Silverfin stores it, so you can tell what a column actually filtered on. Its keys depend on the column's type, and it mirrors internal configuration rather than a payload designed for the API: treat it as informational, expect keys you do not recognise, and do not rely on any single key being present.

Most types share a small vocabulary:

• comparison_mode: how the column matched, on all but a couple of types. One of equal, not_equal, less_than, greater_than, less_than_or_equal, greater_than_or_equal, contains, exactly, is, is not, true, false, up to status, from status, current-user, user, show-all, plus partially_starred on TemplateStarring columns. Match these exactly: the values are not uniformly formatted, and some carry a space or a hyphen rather than an underscore
• comparison_value: the value matched against, for the modes that need one
• filter_data_type: which attribute the column reads, on the types that cover several (CompanyData, SubmissionData)
• filter_data_value: the selected value the column matched on

Some types point at other Silverfin records, which you can resolve through the corresponding API resources:

• firm_workflow_id: the workflow the column reports on. Absent or null means each client file's own default workflow (except on WorkflowUsage, which always names a specific workflow)
• reconciliation_text_id: the reconciliation template
• account_detail_template_id: the account detail template (TemplateStarring)
• workflow_status_id: the workflow status (WorkflowStatus)

Partner references. A segment created from a recommended (partner) template holds firm-agnostic references, which are translated to your firm's ids before the response is built, so you normally see the firm keys above. When your firm has not imported the referenced template the partner reference survives instead (partner_workflow_id, partner_reconciliation_text_id or partner_account_detail_template_id), usually alongside a matching ..._name key carrying the template's name so the column can still be labelled.

matches

Every entry of values carries formatted_value and sort_value (plus filter_error when the value errored), and is null when the run holds no value for that column:

formatted_value is display output, not data. It is built for the Silverfin interface and translated into the profile language of the user the run belongs to, like columns[].name; the Accept-Language header does not affect it. It carries display formatting ("Archived - 45%", "Shared on 04/08/2026", thousands separators). Do not parse it: its wording can change with an interface change. Use sort_value, or the object fields below, when you need a stable value. Object-shaped values can gain fields in a later version, so ignore fields you do not know.

Values by filter type

<table> <thead> <tr> <th>type</th> <th>formatted_value</th> <th>sort_value</th> </tr> </thead> <tbody> <tr> <td><strong>BookyearEnd</strong></td> <td>Book year end as dd/mm/yyyy</td> <td>The same date in ISO 8601 format</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "31/12/2025",&#10; "sort_value": "2025-12-31"&#10;}</code></pre></td> </tr> <tr> <td><strong>CompanyData</strong></td> <td>Depends on settings.filter_data_type: a template, sync entity or mapping list name; mm/yyyy for a date; a translated label for reporting frequency, client type and staff visibility; or the stored attribute for plain columns</td> <td>Usually the same string; reporting frequency is numeric periods per year, creation date is an ISO 8601 timestamp, and last period is an ISO 8601 date</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Limited company",&#10; "sort_value": "Limited company"&#10;}</code></pre></td> </tr> <tr> <td><strong>CompanyGroups</strong></td> <td>Visible groups, comma separated; an empty string when none</td> <td>The same string</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Retail, Flanders",&#10; "sort_value": "Retail, Flanders"&#10;}</code></pre></td> </tr> <tr> <td><strong>FollowCompanies</strong></td> <td>Follower names, comma separated in show-all mode and a single name in user or current-user mode; null in show-all mode when nobody follows</td> <td>The same string or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Marie Dubois, Jan Peeters",&#10; "sort_value": "Marie Dubois, Jan Peeters"&#10;}</code></pre></td> </tr> <tr> <td><strong>Formula</strong></td> <td>Currency-formatted result; null for personal client files</td> <td>Decimal string, including for personal client files</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "1.284.500,00",&#10; "sort_value": "1284500.0"&#10;}</code></pre></td> </tr> <tr> <td><strong>PeriodLocked</strong></td> <td>Object described in <a href="#periodlocked-shape">PeriodLocked shape</a></td> <td>The status string</td> </tr> <tr> <td><strong>PreparationAndReview</strong></td> <td>One of the objects described in <a href="#preparationandreview-shapes">PreparationAndReview shapes</a></td> <td>Completion percentage for a workflow, an ISO 8601 timestamp for one template, or null</td> </tr> <tr> <td><strong>ReconciliationResult</strong></td> <td>A translated Yes/No, dd/mm/yyyy date, currency-formatted number or stored text; a missing value is an empty string, or "0,00" in numeric comparison mode</td> <td>ISO 8601 date, decimal string for numeric modes, or string</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "12.500,00",&#10; "sort_value": "12500.0"&#10;}</code></pre></td> </tr> <tr> <td><strong>SubmissionData</strong></td> <td>Due date as dd/mm/yyyy, or title-cased submission status; null in show-all mode when the client file has no submission of that type, or the submission has no due date</td> <td>ISO 8601 due date, or one of due, overdue, failed, pending, accepted and rejected; null in the same two cases</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "30/09/2026",&#10; "sort_value": "2026-09-30"&#10;}</code></pre><pre><code class="language-json">{&#10; "formatted_value": "Accepted",&#10; "sort_value": "accepted"&#10;}</code></pre></td> </tr> <tr> <td><strong>SyncsInformation</strong></td> <td>String, null, or a sync-status object described in <a href="#syncsinformation-shapes">SyncsInformation shapes</a></td> <td>The string or status</td> </tr> <tr> <td><strong>TemplateStarring</strong></td> <td>Accounts object, reconciliation object, or an empty string when the column does not apply</td> <td>Starred count or flag; see <a href="#templatestarring-shapes">TemplateStarring shapes</a></td> </tr> <tr> <td><strong>Todos</strong></td> <td>Object described in <a href="#todos-shape">Todos shape</a></td> <td>Number of open to-dos</td> </tr> <tr> <td><strong>WorkflowProgress</strong></td> <td>Percentage, optionally prefixed with translated "Archived"; "n/a" when there is no progress; empty string when there is no workflow</td> <td>Number from 0 to 100, or null for the no-progress and no-workflow cases</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "45%",&#10; "sort_value": 45&#10;}</code></pre></td> </tr> <tr> <td><strong>WorkflowSharingStatus</strong></td> <td>Translated "Shared on dd/mm/yyyy", or "Not shared"</td> <td>ISO 8601 share timestamp, or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Shared on 04/08/2026",&#10; "sort_value": "2026-08-04T08:31:00+02:00"&#10;}</code></pre></td> </tr> <tr> <td><strong>WorkflowStatus</strong></td> <td>Workflow status name, or null</td> <td>The same string or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "In progress",&#10; "sort_value": "In progress"&#10;}</code></pre></td> </tr> <tr> <td><strong>WorkflowUsage</strong></td> <td>Translated Yes/No, "Yes" with a translated "default" suffix for the default workflow, or translated "Archived"</td> <td>The same string</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Yes",&#10; "sort_value": "Yes"&#10;}</code></pre></td> </tr> </tbody> </table>

A current-user FollowCompanies column resolves against the user who ran the segment. For an API-started run, this is the token's user.

<hr>

PeriodLocked shape

Always an object except for the filter_error case.

<table> <thead> <tr> <th>field</th> <th>possible values</th> <th>description</th> </tr> </thead> <tbody> <tr> <td><strong>status</strong></td> <td>not_locked, locked, permanently_locked</td> <td>Lock state; also used as sort_value</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">"locked"</code></pre></td> </tr> <tr> <td><strong>locked_at</strong></td> <td>ISO 8601 timestamp or null</td> <td>When the period was locked; null while unlocked</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">"2026-02-14T10:22:31+01:00"</code></pre></td> </tr> <tr> <td><strong>locked_by_name</strong></td> <td>String or null</td> <td>Who locked it; null while unlocked or when a lock has no recorded author</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">"Marie Dubois"</code></pre></td> </tr> </tbody> </table> <hr>

PreparationAndReview shapes

Branch on the key present in formatted_value.

<table> <thead> <tr> <th>shape</th> <th>fields and possible values</th> <th>sort_value</th> </tr> </thead> <tbody> <tr> <td><strong>Nothing to report</strong></td> <td>no_data is always true and is the only key</td> <td>null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "no_data": true&#10; },&#10; "sort_value": null&#10;}</code></pre></td> </tr> <tr> <td><strong>Workflow preparation</strong></td> <td>label is preparation_not_started, partially_prepared or prepared; prepared_count and total_count are numbers; users contains name and user_id</td> <td>prepared_count as a percentage of total_count, rounded down</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "label": "partially_prepared",&#10; "prepared_count": 4,&#10; "total_count": 9,&#10; "users": [&#10; {&#10; "name": "Jan Peeters",&#10; "user_id": 3312&#10; }&#10; ]&#10; },&#10; "sort_value": 44&#10;}</code></pre></td> </tr> <tr> <td><strong>Workflow review</strong></td> <td>label is review_not_started, partially_reviewed or reviewed; reviewed_count excludes invalidated reviews; users contains only reviews that still stand</td> <td>reviewed_count as a percentage of total_count, rounded down</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "label": "partially_reviewed",&#10; "reviewed_count": 2,&#10; "total_count": 8,&#10; "users": [&#10; {&#10; "name": "Marie Dubois",&#10; "user_id": 4471&#10; }&#10; ]&#10; },&#10; "sort_value": 25&#10;}</code></pre></td> </tr> <tr> <td><strong>One template, preparation</strong></td> <td>preparation contains name, user_id and time, or is null when nobody prepared the template</td> <td>Preparation time, or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "preparation": {&#10; "name": "Jan Peeters",&#10; "user_id": 3312,&#10; "time": "2026-07-21T14:03:11.000+02:00"&#10; }&#10; },&#10; "sort_value": "2026-07-21T14:03:11+02:00"&#10;}</code></pre><pre><code class="language-json">{&#10; "formatted_value": {&#10; "preparation": null&#10; },&#10; "sort_value": null&#10;}</code></pre></td> </tr> <tr> <td><strong>One template, review</strong></td> <td>reviews contains name, user_id, time and outdated_at; the run user's review comes first, followed by oldest to newest; invalidated reviews remain; an empty array means nobody reviewed</td> <td>Most recent review time including outdated reviews, or null for an empty array</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "reviews": [&#10; {&#10; "name": "Marie Dubois",&#10; "user_id": 4471,&#10; "time": "2026-07-22T08:15:40.000+02:00",&#10; "outdated_at": null&#10; }&#10; ]&#10; },&#10; "sort_value": "2026-07-22T08:15:40+02:00"&#10;}</code></pre></td> </tr> </tbody> </table>

Workflow users array order is not significant.

<hr>

SyncsInformation shapes

settings.scope_type selects the shape. settings.category selects the bookkeeping or administration connection; null or absent means bookkeeping.

<table> <thead> <tr> <th>scope_type</th> <th>formatted_value</th> <th>sort_value</th> </tr> </thead> <tbody> <tr> <td><strong>sync_name</strong></td> <td>Sync name, or null with no connection</td> <td>The same string or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Exact Online",&#10; "sort_value": "Exact Online"&#10;}</code></pre></td> </tr> <tr> <td><strong>sync_type</strong></td> <td>Sync type, or null with no connection</td> <td>The same string or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "ExactOnline",&#10; "sort_value": "ExactOnline"&#10;}</code></pre></td> </tr> <tr> <td><strong>sync_reference</strong></td> <td>Client name with its reference in brackets, bare reference when the name cannot be resolved, or null with no connection</td> <td>The same string or null</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "Acme NV (ACME001)",&#10; "sort_value": "Acme NV (ACME001)"&#10;}</code></pre></td> </tr> <tr> <td><strong>sync_status</strong></td> <td>Object whose fields depend on status</td> <td>The status</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "status": "failed",&#10; "timestamp": "2026-08-03T22:05:12+02:00",&#10; "error_message": "An error has occurred."&#10; },&#10; "sort_value": "failed"&#10;}</code></pre></td> </tr> </tbody> </table>

error_message is readable interface text rather than raw internals. It can contain simple HTML markup such as <strong>.

<hr>

TemplateStarring shapes

<table> <thead> <tr> <th>kind</th> <th>formatted_value fields</th> <th>sort_value</th> </tr> </thead> <tbody> <tr> <td><strong>accounts</strong></td> <td>status is starred, partially_starred or not_starred; starred_count and total_count are numbers</td> <td>Starred count</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "kind": "accounts",&#10; "status": "partially_starred",&#10; "starred_count": 2,&#10; "total_count": 5&#10; },&#10; "sort_value": 2&#10;}</code></pre></td> </tr> <tr> <td><strong>reconciliation</strong></td> <td>starred is true or false</td> <td>1 when starred, 0 otherwise</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": {&#10; "kind": "reconciliation",&#10; "starred": true&#10; },&#10; "sort_value": 1&#10;}</code></pre></td> </tr> <tr> <td><strong>Not applicable</strong></td> <td>Empty string when no period accounts belong to the account detail template, or the client file has no such reconciliation</td> <td>-1 for accounts, 0 for reconciliation</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">{&#10; "formatted_value": "",&#10; "sort_value": -1&#10;}</code></pre></td> </tr> </tbody> </table> <hr>

Todos shape

Always an object except for the filter_error case.

<table> <thead> <tr> <th>field</th> <th>possible values</th> <th>description</th> </tr> </thead> <tbody> <tr> <td><strong>status</strong></td> <td>not_done, partially_done, done, null</td> <td>Completion state; null when the period has no to-dos</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">"partially_done"</code></pre></td> </tr> <tr> <td><strong>completed</strong></td> <td>Number</td> <td>How many to-dos are done</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">3</code></pre></td> </tr> <tr> <td><strong>total</strong></td> <td>Number</td> <td>How many to-dos there are</td> </tr> <tr> <td></td> <td colspan="2"><pre><code class="language-json">7</code></pre></td> </tr> </tbody> </table>

sort_value is the number of open to-dos, total minus completed.

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:read

{
  "columns": [
    {
      "type": "Todos",
      "name": "To-dos"
    }
  ]
}