Get run results | Instabase AI Hub Documentation

Get the results of a completed automation app run.

The results from this endpoint are paginated. The has_more field in the response indicates if there are more results to fetch and the file_offset query parameter can be used to specify the starting point for the next set of results.

For an example of using file_offset to fetch all results, see the Retrieving paginated results code sample.

This API operation might return field names that differ from those in the automation project. The operation converts field names to valid Python variable names by:

Allowing only letters, numbers, and underscores
Requiring names to start with a letter or underscore
Replacing invalid characters with underscores
Converting single underscores to double underscores

Examples:

due date → due_date
driver's license → driver_s_license
3rd category → _3rd_category
secret_id → secret__id

These changes apply only to field names in the API response. The field names in the automation project are not changed.

Get the results of a completed automation app run. <Note> The results from this endpoint are paginated. The `has_more` field in the response indicates if there are more results to fetch and the `file_offset` query parameter can be used to specify the starting point for the next set of results. For an example of using `file_offset` to fetch all results, see the *Retrieving paginated results* code sample. </Note> <Info> This API operation might return field names that differ from those in the automation project. The operation converts field names to valid Python variable names by: * Allowing only letters, numbers, and underscores * Requiring names to start with a letter or underscore * Replacing invalid characters with underscores * Converting single underscores to double underscores Examples: * `due date` → `due_date` * `driver's license` → `driver_s_license` * `3rd category` → `_3rd_category` * `secret_id` → `secret__id` These changes apply only to field names in the API response. The field names in the automation project are not changed. </Info>

Authentication

AuthorizationBearer

Bearer HTTP authentication.

Path parameters

run_idstringRequired

The run ID.

Headers

IB-ContextstringOptional

Specify whether to use your community account or organization account to complete the request. To use your community account, define as your user ID. To use your organization account, define as your organization ID. If unspecified, defaults to community account context. See Authorization and context identification for details.

Specify whether to use your community account or organization account to complete the request. To use your community account, define as your user ID. To use your organization account, define as your organization ID. If unspecified, defaults to community account context. See [Authorization and context identification](/api-sdk/authorization#ib-context-header) for details.

Query parameters

include_review_resultsbooleanOptionalDefaults to false

Whether to include human review details in the results. When set to true, various human review details are returned.

The review process can include manually correcting values. This endpoint doesn’t support returning the original and corrected values.

The following values are returned at the document level (files/documents/...):

review_completed
class_edit_history
class_edit_history/timestamp
class_edit_history/user_id
class_edit_history/modifications
class_edit_history/modifications/message

The following values are returned at the field level (files/documents/fields/...):

edit_history
edit_history/timestamp
edit_history/user_id
edit_history/modifications
edit_history/modifications/message

The following values are returned at the packet level (also known as case level) (case_info/fields/...):

edit_history
edit_history/timestamp
edit_history/user_id
edit_history/modifications
edit_history/modifications/message

See the response schema for details and descriptions.

Whether to include human review details in the results. When set to `true`, various human review details are returned. <Note>The review process can include manually correcting values. This endpoint doesn't support returning the original and corrected values.</Note> The following values are returned at the document level (`files/documents/...`): - `review_completed` - `class_edit_history` - `class_edit_history/timestamp` - `class_edit_history/user_id` - `class_edit_history/modifications` - `class_edit_history/modifications/message` The following values are returned at the field level (`files/documents/fields/...`): - `edit_history` - `edit_history/timestamp` - `edit_history/user_id` - `edit_history/modifications` - `edit_history/modifications/message` The following values are returned at the packet level (also known as case level) (`case_info/fields/...`): - `edit_history` - `edit_history/timestamp` - `edit_history/user_id` - `edit_history/modifications` - `edit_history/modifications/message` See the response schema for details and descriptions.

include_confidence_scoresbooleanOptionalDefaults to false

Whether to include confidence scores in the results. When set to true, various confidence scores are returned.

The following values are returned at the document level (files/documents/...):

classification_confidence

The following values are returned at the field level (files/documents/fields/...):

confidence/model
confidence/ocr

See the response schema for details and descriptions.

Whether to include confidence scores in the results. When set to `true`, various confidence scores are returned. The following values are returned at the document level (`files/documents/...`): - `classification_confidence` The following values are returned at the field level (`files/documents/fields/...`): - `confidence/model` - `confidence/ocr` See the response schema for details and descriptions.

include_validation_resultsbooleanOptionalDefaults to false

Whether to include validation status in the results. When set to true, various validation results are returned.

The following values are returned at the document level (files/documents/...):

validations/final_result_pass

The following values are returned at the field level (files/documents/fields/...):

validations/valid
validations/alerts

The following values are returned at the packet level (also known as case level) (case_info/fields/...):

validations/valid
validations/failures

Cross-class validation ensures data quality and consistency across documents within a packet.

See the response schema for details and descriptions.

Whether to include validation status in the results. When set to `true`, various validation results are returned. The following values are returned at the document level (`files/documents/...`): - `validations/final_result_pass` The following values are returned at the field level (`files/documents/fields/...`): - `validations/valid` - `validations/alerts` The following values are returned at the packet level (also known as case level) (`case_info/fields/...`): - `validations/valid` - `validations/failures` Cross-class validation ensures data quality and consistency across documents within a packet. See the response schema for details and descriptions.

include_source_infobooleanOptionalDefaults to false

Whether to include source information in the results. When set to true, various source details are returned.

The following values are returned at the document level (files/documents/...):

post_processed_paths
post_processed_pdf_path

A post_processed_pdf_path is populated when settings/runtime_config/generate_post_process_pdf=true. Paths to PDFs are generated from each document, with separate PDF paths for documents split during classification.
page_layouts

The following values are returned at the field level (files/documents/fields/...):

source_coordinates/top_x
source_coordinates/top_y
source_coordinates/bottom_x
source_coordinates/bottom_y
source_coordinates/page_number

See the response schema for details and descriptions.

Whether to include source information in the results. When set to `true`, various source details are returned. The following values are returned at the document level (`files/documents/...`): - `post_processed_paths` - `post_processed_pdf_path` <Note> A `post_processed_pdf_path` is populated when `settings/runtime_config/generate_post_process_pdf=true`. Paths to PDFs are generated from each document, with separate PDF paths for documents split during classification. </Note> - `page_layouts` The following values are returned at the field level (`files/documents/fields/...`): - `source_coordinates/top_x` - `source_coordinates/top_y` - `source_coordinates/bottom_x` - `source_coordinates/bottom_y` - `source_coordinates/page_number` See the response schema for details and descriptions.

file_offsetintegerOptionalDefaults to 0

The initial file index to start returning results from. Defaults to 0.

Response

Run results retrieved successfully.

If errors occur at the class, field, or document levels, the response status code is 200 and the response body includes error details.

Run results retrieved successfully. <Note> If errors occur at the class, field, or document levels, the response status code is `200` and the response body includes error details. </Note>

idstring or null

Run ID of the run.

statusenum or null

Status of the run. Possible values and meanings:

CANCELLED — A user cancelled the run
COMPLETE — The run successfully completed. A human review completed if it was required. Results are retrievable, but some fields may have failed and have the value ERROR.
FAILED — The run failed to complete
PAUSED — This status is reserved for future use
RUNNING — The run is in progress and is not paused
STOPPED_AT_CHECKPOINT — A validation error has paused the run for human review

Status of the run. Possible values and meanings: - `CANCELLED` -- A user cancelled the run - `COMPLETE` -- The run successfully completed. A human review completed if it was required. Results are retrievable, but some fields may have failed and have the value `ERROR`. - `FAILED` -- The run failed to complete - `PAUSED` -- This status is reserved for future use - `RUNNING` -- The run is in progress and is not paused - `STOPPED_AT_CHECKPOINT` -- A validation error has paused the run for human review

messagestring or null

Message about the run.

start_timestamplong or null

When the run started, in Unix time nanoseconds.

finish_timestamplong or null

When the run finished, in Unix time nanoseconds. null if run is still in progress.

batch_idstring or null

The batch ID used as input for this run, if run using a batch.

fileslist of objects or null

keysobject or null

case_infoobject or null

Packet-level information (also known as case-level information) captured for the run, including optional edit history per cross-class field when include_review_results=true.

Cross-class fields consolidate data extracted from standard fields within a packet. For more information about packets and cross-class fields, see Extracting data from packets.

Packet-level information (also known as case-level information) captured for the run, including optional edit history per cross-class field when `include_review_results=true`. Cross-class fields consolidate data extracted from standard fields within a packet. For more information about packets and cross-class fields, see [Extracting data from packets](/automate/packet-schema).

review_completedboolean or null

Indicates whether the run or document has completed review.

has_moreboolean or null

Indicates whether additional results are available beyond those included in the current response. Use the file_offset query parameter to specify the starting point when fetching the next set of results.

Whether to include human review details in the results. When set to true, various human review details are returned.

The review process can include manually correcting values. This endpoint doesn’t support returning the original and corrected values.

The following values are returned at the document level (files/documents/...):

review_completed
class_edit_history
class_edit_history/timestamp
class_edit_history/user_id
class_edit_history/modifications
class_edit_history/modifications/message

The following values are returned at the field level (files/documents/fields/...):

edit_history
edit_history/timestamp
edit_history/user_id
edit_history/modifications
edit_history/modifications/message

The following values are returned at the packet level (also known as case level) (case_info/fields/...):

edit_history
edit_history/timestamp
edit_history/user_id
edit_history/modifications
edit_history/modifications/message

See the response schema for details and descriptions.

1	from aihub import AIHub
2
3	client = AIHub(
4	api_root="https://aihub.instabase.com/api",
5	api_key="abcdefghijklmnopqrst1234567890",
6	ib_context="john.doe_acme.com"
7	)
8
9	results = client.apps.runs.results(
10	run_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
11	)
12
13	print(f"Retrieved results from {len(results.files)} files")

1	{
2	"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3	"status": "COMPLETE",
4	"message": "Completed single_flow",
5	"start_timestamp": 1765912514238248700,
6	"finish_timestamp": 1765912529614834000,
7	"batch_id": "1235",
8	"files": [
9	{
10	"original_file_name": "test.png",
11	"input_file_path": "instabase-sandbox-org/test-org/fs/Instabase Drive/app-runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/input/test.png",
12	"documents": [
13	{
14	"fields": [
15	{
16	"field_name": "employers_address_and_ZIP_code",
17	"value": "123 STREET RD ANYWHERE, USA,12345",
18	"type": "TEXT"
19	}
20	],
21	"class_name": "Wage And Tax Statement",
22	"page_numbers": [
23	1,
24	2
25	]
26	}
27	]
28	},
29	{
30	"original_file_name": "test2.png",
31	"input_file_path": "instabase-sandbox-org/test-org/fs/Instabase Drive/app-runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/input/test2.png",
32	"documents": [
33	{
34	"fields": [
35	{
36	"field_name": "sex",
37	"value": "Male",
38	"type": "TEXT"
39	}
40	],
41	"class_name": "Driver License",
42	"page_numbers": [
43	1
44	]
45	}
46	]
47	}
48	],
49	"keys": [
50	{
51	"custom": {}
52	}
53	],
54	"case_info": {
55	"fields": [
56	{
57	"name": "Employee_Address",
58	"value": "123 STREET RD ANYWHERE, USA,12345",
59	"input_fields": [
60	{
61	"record_index": 0,
62	"refined_phrase_name": "employers_address_and_ZIP_code"
63	}
64	],
65	"chosen_field": {
66	"record_index": 0,
67	"refined_phrase_name": "employers_address_and_ZIP_code"
68	},
69	"edit_history": [
70	{
71	"timestamp": "08/27/2025 00:58:39",
72	"user_id": "john.doe_instabase.com",
73	"modifications": [
74	{
75	"message": "Edited to \"123 STREET RD ANYWHERE, USA,12345\""
76	}
77	]
78	}
79	]
80	},
81	{
82	"name": "Sex",
83	"value": "Male",
84	"input_fields": [
85	{
86	"record_index": 0,
87	"refined_phrase_name": "sex"
88	}
89	],
90	"chosen_field": {
91	"record_index": 0,
92	"refined_phrase_name": "sex"
93	}
94	}
95	]
96	},
97	"has_more": false
98	}