Run results endpoint

Table of Contents

Access app run results by sending a POST request to URL_BASE/api/v1/flow_binary/results with the request body encoded as JSON.

Method	Syntax
POST	`URL_BASE/api/v1/flow_binary/results`

Request parameters

Parameters are required unless marked as optional.

Parameter	Type	Description	Values
`ibresults_path`	string	The path to a `batch.ibflowresults` file
`options`	Dict	Optional. JSON dictionary with options to return additional metadata.	`include_checkpoint_results`, `provenance_info`, `include_page_layouts`
`include_page_layouts`	Boolean	Optional. Whether to include `page_layout` information about the original input document.	Defaults to `false`.
`include_checkpoint_results`	Boolean	Optional. Whether to include validation information in the response.	Defaults to `false`.
`refined_phrases_features`	List[string]	Experimental for AI Hub. Optional. Include entry `'provenance info'` in list to include extracted word position information.
`internal_keys`	Boolean	Optional. Include hidden fields (i.e. fields with field names that start with `__`)
`file_offset`	integer	Optional (defaults to 0). Initial file index to start returning results from. Use this when dealing with large results that are paginated and exceed the default limit of 20 that is returned by the API.	Integer specifying a file index. Defaults to 0.

Response schema

Not all keys are returned in the response by default. Some are gated on the options passed in through the request.

Key	Type	Description	Value
`records`	Array	Array of all the results by records
`record/output_file_path`	string	The output ibdoc the record was retrieved from
`record/results`	Array	The set of extracted phrases by field names
`record/results/key`	string	field key. An internal field has __ (double underscore) as a prefix
`record/results/value`	string	field value. If the field results has an error value is “ERROR”
`record/results/field_type`	string	field type. Extracted type of the field. Must be one of the following: ANY, TEXT, INT, FLOAT, DICT, LIST, BOOL, TABLE, IMG, EXTRACTED_TABLE, EXTRACTED_TABLE_LIST, SELECT
`record/results/provenance`	Dict	Source metadata on extracted value location
`record/results/model_confidence`	float	Average model confidence for the extracted value
`record/results/ocr_confidence`	float	Average OCR confidence for the extracted value
`record/results/information_regions`	List	List of bounding boxes in the pixel space of what anchor information was used to extract the field
`record/results/information_text_regions`	List	List of bounding boxes in the OCR text space of what anchor information was used to extract the field
`record/results/extracted_regions`	List	List of bounding boxes in the pixel space of where the extracted value is on the document
`record/results/extracted_text_regions`	List	List of bounding boxes in the OCR text space of where the extracted value is on the document
`record/results/error_msg`	string	Error message - only exists when value is `ERROR`.
`record/record_index`	integer	Record index in output path.
`record/file_name`	string	Name of the original document.
`record/is_manually_reviewed`	string	If the record is manually marked as reviewed
`record/checkpoint_results`	Dict	The full path to the root output folder.	A string showing the output folder path.
`record/checkpoint_results/flow_path_in_binary`	string	Path to the binary
`record/checkpoint_results/record_index`	integer	Record index of the checkpoint result
`record/checkpoint_results/results`	Dict	The full path to the root output folder.	A string showing the output folder path.
`record/checkpoint_results/results/valid`	Boolean	If the validation function passed
`record/checkpoint_results/results/fields`	Array	Array of all fields passed to this validation function
`record/checkpoint_results/results/msg`	string	Validation message
`record/checkpoint_results/results/type`	string	Type of validation done.	’extraction-custom’, ‘classification_custom’, ’typecheck’
`record/layout`	Dict	Page metadata and information
`record/layout/page_layouts`	Array	List of page layouts
`record/layout/page_layouts/page_number`	integer	Page number
`record/layout/page_layouts/processed_image_path`	string	Image path to the generated image
`record/layout/page_layouts/width`	integer	Width of image
`record/layout/page_layouts/height`	integer	Height of image
`record/layout/page_layouts/corrected_rotation`	integer	Rotation angle of document
`record/layout/page_layouts/is_image_page`	Boolean	Whether the page is an image
`record/layout/page_layouts/origin_pos`	Array	Original position of the document
`record/layout/page_layouts/origin_pos/x`	integer	x coordinate
`record/layout/page_layouts/origin_pos/y`	integer	y coordinate
`record/layout/document_path`	string	Path to the original document
`record/error`	Dict	Only if a record fails
`record/error/error_message`	string	Error message for the record.
`record/error/error_type`	string	Error type
`record/error/step_name`	string	Flow step where error occurred

Examples

Request

Example (Python):

url = url_base + '/api/v1/flow_binary/results'

args = {
  'ibresults_path': "/jaydoe/my_repo/fs/Instabase Drive/flow_proj/out/batch.ibflowresults",
  'options': {
    'refined_phrases_features': ['provenance_info'],
    'include_page_layouts': True,
  },
  'file_offset': 0
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Full Pagination Example (Python):

url = url_base + '/api/v1/flow_binary/results'

args = {
  'ibresults_path': "/jaydoe/my_repo/fs/Instabase Drive/flow_proj/out/batch.ibflowresults",
  'options': {
    'refined_phrases_features': ['provenance_info'],
    'include_page_layouts': True,
  },
  'file_offset': 0
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

# Parse through pages until no more pages left to look through
all_records = [resp_data.get('records', [])]
while len(resp_data) > 0:
  # Retrieve the last file_index from the last record returned
  next_file_offset = resp_data['records'][-1]['file_index'] + 1
  args['file_offset'] = next_file_offset
  json_data = json.dumps(args)

  r = requests.post(url, data=json_data, headers=headers)
  resp_data = json.loads(r.content)
  resp_records = resp_data.get('records', [])

  all_records.extend(resp_records)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  records: [
    {
      "output_file_path": "path/to/my/output.ibdoc",
      "results": [
        {
          "key": "field1",
          "value": "value1",
          "model_confidence": 0.43
        }...,
        {
          "key": "field2",
          "value": "ERROR",
          "error_msg": "Some error happened (line: 120)",
          "ocr_confidence": 0.98
        },
        {
          "key": "__hidden_field3",
          "value": "value3"
        },
      ],
      "record_index": 0,
      "file_name": "document.pdf",
      "layout": {
        "page_layouts": [
          {
            "page_number": 0,
            "processed_image_path": "path/to/generated/image",
            "width": 600,
            "height": 800,
            "corrected_rotation": 0,
            "is_image_page": false,
            "origin_pos": {
              "x": 0.0,
              "y": 0.0
            }
          }..., //more pages
        ]
      },
      "document_path": "path/to/my/original/document.pdf"
    },
    {
      "error": {
        "error_message": "Columns failed: field1",
        "error_type": "process_files_failed",
        "step_name": "process_files"
      },
      "file_name": "error.pdf"
    }..., // more records
  ]
}