--- title: "Fetch the results of the latest run of an Insights segment" method: GET path: "/api/v4/f/{firm_id}/segments/{id}/results" tags: ["Insights"] --- # Fetch the results of the latest run of an Insights segment `GET /api/v4/f/{firm_id}/segments/{id}/results` ## Request - Base URL: `https://live.getsilverfin.com` - URL: `https://live.getsilverfin.com/api/v4/f/{firm_id}/segments/{id}/results` - Auth: OAuth 2 - Authorization code: `https://live.getsilverfin.com/oauth/authorize` - Token URL: `https://live.getsilverfin.com/oauth/token` scopes: `insights:read` 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: ```json { "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." } ``` | field | description | | ----- | ----------- | | **status** | always `pending` here; `pending` and `finished` are the only values this field ever takes | **request_ref** | reference of the pending run | **started_at** | when the run was created (ISO 8601) | **finished_at** | always `null` while the run is pending | **progress** | `processed_companies`: how many companies the run has processed so far. Informational only: a run with slow filters evaluates companies in two passes and can count a company in both, so it is not a fraction of a known total | **message** | a human-readable hint. Of the pending payloads, only this endpoint's 202 carries it `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: ```json { "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 | field | description | | ----- | ----------- | | **status** | `finished` for a results payload, `pending` on the pending payload above; these are the only two values | **request_ref** | reference of the run the results come from | **started_at** | when the run was created (ISO 8601) | **finished_at** | when the segment run finished (ISO 8601) | **period_selection** | How the run picked each company's period: | **columns** | one entry per column of the run, in column order | **matches** | the companies that matched, one page at a time, ordered by company name | **pagination** | `page`, `per_page`, `total_matches`, `total_pages`; the `Total` and `Per-Page` response headers carry the same totals | **non_match_count** | how many of your accessible companies did not match Timestamps are ISO 8601 with the server's UTC offset (e.g. `+02:00`). ### columns | field | description | | ----- | ----------- | | **uuid** | the key this column's value appears under in each match's `values` | **type** | the filter type, e.g. `WorkflowProgress` (see [values by filter type](#values-by-filter-type)) | **name** | the column's display name, in the profile language of the user the run belongs to; an empty string for a column that was never named | **settings** | the filter's configuration: what the column filters on `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 | field | description | | ----- | ----------- | | **company_id** | id of the client file | **company_name** | name of the client file | **period_id** | id of the period the run evaluated for this company | **period_end_date** | end date of that period (ISO 8601) | **values** | an object keyed by column `uuid` 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: | field | description | | ----- | ----------- | | **formatted_value** | the value as Silverfin displays it; see [values by filter type](#values-by-filter-type) | **sort_value** | a sortable representation of the same value | **filter_error** | only present when the filter could not be evaluated for this company; the message says why, and `formatted_value` and `sort_value` then repeat that message instead of a value **`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
type formatted_value sort_value
BookyearEnd Book year end as dd/mm/yyyy The same date in ISO 8601 format 
{
  "formatted_value": "31/12/2025",
  "sort_value": "2025-12-31"
}
CompanyData 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 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 
{
  "formatted_value": "Limited company",
  "sort_value": "Limited company"
}
CompanyGroups Visible groups, comma separated; an empty string when none The same string 
{
  "formatted_value": "Retail, Flanders",
  "sort_value": "Retail, Flanders"
}
FollowCompanies 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 The same string or null 
{
  "formatted_value": "Marie Dubois, Jan Peeters",
  "sort_value": "Marie Dubois, Jan Peeters"
}
Formula Currency-formatted result; null for personal client files Decimal string, including for personal client files 
{
  "formatted_value": "1.284.500,00",
  "sort_value": "1284500.0"
}
PeriodLocked Object described in PeriodLocked shape The status string
PreparationAndReview One of the objects described in PreparationAndReview shapes Completion percentage for a workflow, an ISO 8601 timestamp for one template, or null
ReconciliationResult 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 ISO 8601 date, decimal string for numeric modes, or string 
{
  "formatted_value": "12.500,00",
  "sort_value": "12500.0"
}
SubmissionData 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 ISO 8601 due date, or one of due, overdue, failed, pending, accepted and rejected; null in the same two cases 
{
  "formatted_value": "30/09/2026",
  "sort_value": "2026-09-30"
}
{
  "formatted_value": "Accepted",
  "sort_value": "accepted"
}
SyncsInformation String, null, or a sync-status object described in SyncsInformation shapes The string or status
TemplateStarring Accounts object, reconciliation object, or an empty string when the column does not apply Starred count or flag; see TemplateStarring shapes
Todos Object described in Todos shape Number of open to-dos
WorkflowProgress Percentage, optionally prefixed with translated "Archived"; "n/a" when there is no progress; empty string when there is no workflow Number from 0 to 100, or null for the no-progress and no-workflow cases 
{
  "formatted_value": "45%",
  "sort_value": 45
}
WorkflowSharingStatus Translated "Shared on dd/mm/yyyy", or "Not shared" ISO 8601 share timestamp, or null 
{
  "formatted_value": "Shared on 04/08/2026",
  "sort_value": "2026-08-04T08:31:00+02:00"
}
WorkflowStatus Workflow status name, or null The same string or null 
{
  "formatted_value": "In progress",
  "sort_value": "In progress"
}
WorkflowUsage Translated Yes/No, "Yes" with a translated "default" suffix for the default workflow, or translated "Archived" The same string 
{
  "formatted_value": "Yes",
  "sort_value": "Yes"
}
A current-user FollowCompanies column resolves against the user who ran the segment. For an API-started run, this is the token's user.
### PeriodLocked shape Always an object except for the `filter_error` case.
field possible values description
status not_locked, locked, permanently_locked Lock state; also used as sort_value 
"locked"
locked_at ISO 8601 timestamp or null When the period was locked; null while unlocked 
"2026-02-14T10:22:31+01:00"
locked_by_name String or null Who locked it; null while unlocked or when a lock has no recorded author 
"Marie Dubois"
### PreparationAndReview shapes Branch on the key present in `formatted_value`.
shape fields and possible values sort_value
Nothing to report no_data is always true and is the only key null 
{
  "formatted_value": {
    "no_data": true
  },
  "sort_value": null
}
Workflow preparation label is preparation_not_started, partially_prepared or prepared; prepared_count and total_count are numbers; users contains name and user_id prepared_count as a percentage of total_count, rounded down 
{
  "formatted_value": {
    "label": "partially_prepared",
    "prepared_count": 4,
    "total_count": 9,
    "users": [
      {
        "name": "Jan Peeters",
        "user_id": 3312
      }
    ]
  },
  "sort_value": 44
}
Workflow review label is review_not_started, partially_reviewed or reviewed; reviewed_count excludes invalidated reviews; users contains only reviews that still stand reviewed_count as a percentage of total_count, rounded down 
{
  "formatted_value": {
    "label": "partially_reviewed",
    "reviewed_count": 2,
    "total_count": 8,
    "users": [
      {
        "name": "Marie Dubois",
        "user_id": 4471
      }
    ]
  },
  "sort_value": 25
}
One template, preparation preparation contains name, user_id and time, or is null when nobody prepared the template Preparation time, or null 
{
  "formatted_value": {
    "preparation": {
      "name": "Jan Peeters",
      "user_id": 3312,
      "time": "2026-07-21T14:03:11.000+02:00"
    }
  },
  "sort_value": "2026-07-21T14:03:11+02:00"
}
{
  "formatted_value": {
    "preparation": null
  },
  "sort_value": null
}
One template, review 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 Most recent review time including outdated reviews, or null for an empty array 
{
  "formatted_value": {
    "reviews": [
      {
        "name": "Marie Dubois",
        "user_id": 4471,
        "time": "2026-07-22T08:15:40.000+02:00",
        "outdated_at": null
      }
    ]
  },
  "sort_value": "2026-07-22T08:15:40+02:00"
}
Workflow `users` array order is not significant.
### SyncsInformation shapes `settings.scope_type` selects the shape. `settings.category` selects the bookkeeping or administration connection; null or absent means bookkeeping.
scope_type formatted_value sort_value
sync_name Sync name, or null with no connection The same string or null 
{
  "formatted_value": "Exact Online",
  "sort_value": "Exact Online"
}
sync_type Sync type, or null with no connection The same string or null 
{
  "formatted_value": "ExactOnline",
  "sort_value": "ExactOnline"
}
sync_reference Client name with its reference in brackets, bare reference when the name cannot be resolved, or null with no connection The same string or null 
{
  "formatted_value": "Acme NV (ACME001)",
  "sort_value": "Acme NV (ACME001)"
}
sync_status Object whose fields depend on status The status 
{
  "formatted_value": {
    "status": "failed",
    "timestamp": "2026-08-03T22:05:12+02:00",
    "error_message": "An error has occurred."
  },
  "sort_value": "failed"
}
| status | timestamp | error_message | meaning | | ------ | --------- | ------------- | ------- | | **synchronised** | Present | Absent | Last sync completed | | **failed** | Present | Present, but can be null | Last sync faulted | | **canceled** | Present | Absent | Last sync was cancelled | | **in_progress** | Absent | Absent | Sync is running or queued | | **not_synchronised** | Absent | Absent | No sync connection | | **no_sync_data** | Absent | Absent | Connected, but nothing has synced yet | `error_message` is readable interface text rather than raw internals. It can contain simple HTML markup such as ``.
### TemplateStarring shapes
kind formatted_value fields sort_value
accounts status is starred, partially_starred or not_starred; starred_count and total_count are numbers Starred count 
{
  "formatted_value": {
    "kind": "accounts",
    "status": "partially_starred",
    "starred_count": 2,
    "total_count": 5
  },
  "sort_value": 2
}
reconciliation starred is true or false 1 when starred, 0 otherwise 
{
  "formatted_value": {
    "kind": "reconciliation",
    "starred": true
  },
  "sort_value": 1
}
Not applicable Empty string when no period accounts belong to the account detail template, or the client file has no such reconciliation -1 for accounts, 0 for reconciliation 
{
  "formatted_value": "",
  "sort_value": -1
}
### Todos shape Always an object except for the `filter_error` case.
field possible values description
status not_done, partially_done, done, null Completion state; null when the period has no to-dos 
"partially_done"
completed Number How many to-dos are done 
3
total Number How many to-dos there are 
7
`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.
Required scope: `insights:read` ## Path parameters - `firm_id` integer, required - `id` integer, required ## Query parameters - `page` integer - `per_page` integer ## Response `200` The results of the latest finished run - InsightsSegmentResults - `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 - `period_selection` InsightsPeriodSelection, required - `type` 'financial_year' | 'accounting_period' | 'active_period' | 'completed_period', required - `date` string, date, nullable: Present for financial_year and accounting_period selections - `locking_type` 'locked' | 'permanently_locked', nullable: Present for active_period and completed_period selections - `columns` InsightsSegmentColumn[], required - `uuid` string, uuid, required: Correlates this column with values in this response only; it is not a stable identifier across runs. - `type` string, nullable, required - `name` string, nullable, required - `settings` object, nullable, required - `matches` InsightsSegmentMatch[], required - `company_id` integer, required - `company_name` string, required - `period_id` integer, required - `period_end_date` string, date, required - `values` object, required: Values keyed by the corresponding column uuid - `pagination` InsightsPagination, required - `page` integer, required - `per_page` integer, required - `total_matches` integer, required - `total_pages` integer, required - `non_match_count` integer, required ## Other responses - `202`: The latest run is still in progress; its status and progress are returned - `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 or is not accessible, or no calculated results are available ## 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/results/get.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)