App runs endpoint

The App runs endpoint lets you create an app run for an AI Hub app and returns a run ID. A deployment-specific version lets you run deployments, also returning a run ID. You can then use the run ID to check the status of an app or deployment run and, when complete, get the results.

Run app

Description

Run an app by its name or app ID by sending a POST request to API_ROOT/v2/apps/runs. The input for the run is specified using a batch ID or an input file path. To run deployments by API, use the Run deployment endpoint.

Request body

Parameters are required unless marked as optional.

Response status

Response schema

The response body is a JSON object known as a run object. The run object provides information about the run and its progress, but not the run results. You can use the run’s id to poll the Run status endpoint and the Run results endpoint.

Examples

Request (curl)

$
curl "${API_ROOT}/v2/apps/runs" \
>
  -H "Authorization: Bearer ${API_TOKEN}" \
>
  -H "IB-Context: ${IB_CONTEXT}"\
>
  -H "Content-Type: application/json" \
>
  -d '{
>
        "batch_id": "<BATCH-ID>",
>
        "app_name": "<APP-NAME>"
>
      }'

Request (Python SDK)

1
from aihub import AIHub
2
3
client = AIHub(api_root="<API-ROOT>",
4
               api_key="<API-TOKEN>",
5
               ib_context="<IB-CONTEXT>")
6
result = client.apps.runs.create(app_name='<APP-NAME>',
7
                                 batch_id='<BATCH-ID>')

Response

1
{
2
  "id": "<RUN-ID>",
3
  "status": "RUNNING",
4
  "msg": "",
5
  "start_timestamp": 1709592306000,
6
  "finish_timestamp": null,
7
}

Run deployment

Description

Run a deployment by sending a POST request to API_ROOT/v2/aihub/deployments/<DEPLOYMENT-ID>/run, using the request URL to specify the ID of the deployment. The input for the run is specified using a batch ID or an input file path.

Request body

Parameters are required unless marked as optional.

Response status

Response schema

The response body contains the run ID, that you can use to poll the Run status endpoint and the Run results endpoint.

Examples

Request (curl)

$
curl "${API_ROOT}/v2/aihub/deployments/<DEPLOYMENT-ID>/run" \
>
  -H "Authorization: Bearer ${API_TOKEN}" \
>
  -H "IB-Context: ${IB_CONTEXT}"\
>
  -H "Content-Type: application/json" \
>
  -d '{
>
        "batch_id": "<BATCH-ID>",
>
      }'

Response

1
{
2
  "job_id": "<RUN-ID>",
3
}

Run status

Description

Get the status of a run by sending a GET request to API_ROOT/v2/apps/runs/<RUN-ID>. The run’s id value is returned in the response of the initial run.

Request body

There is no request body. Use the request URL to specify a run id.

Response status

Response schema

The response body is a JSON object known as a run object. The run object provides information about the run and its progress, but not the run results. You can use the run’s id to poll the Run results endpoint.

Examples

Request (curl)

$
curl "${API_ROOT}/v2/apps/runs/<RUN-ID>" \
>
  -H "Authorization: Bearer ${API_TOKEN}"\
>
  -H "IB-Context: ${IB_CONTEXT}"

Request (Python SDK)

1
from aihub import AIHub
2
3
client = AIHub(api_root="<API-ROOT>",
4
               api_key="<API-TOKEN>",
5
               ib_context="<IB-CONTEXT>")
6
status = client.apps.runs.status('<RUN-ID>')

Response

1
{
2
  "id": "<RUN-ID>",
3
  "status": "COMPLETE",
4
  "msg": "Completed",
5
  "start_timestamp": 1709592306000,
6
  "finish_timestamp": 1709592306500,
7
}

Run results

Description

Get the results of a completed run by sending a GET request to API_ROOT/v2/apps/runs/<RUN-ID>/results. The run id value is returned in the response of the initial run.

Query parameters

Response status

Response schema

The response body is a JSON object containing the results of the run.

For each extracted field, there is a <DOCUMENT-FIELD> object structure:

Depending on the included query parameters, the following information can also be included in the results.

include_review_results

The following fields are included in the response when using the include_review_results query parameter.

Run or document level:

Extracted field level:

include_confidence_scores

The following fields are included in the response when using the include_confidence_scores query parameter.

Run or document level:

Extracted field level:

include_validation_results

The following fields are included in the response when using the include_validation_results query parameter.

Run or document level:

Extracted field level:

include_source_info

The following fields are included in the response when using the include_source_info query parameter.

Run or document level:

Extracted field level:

Examples

Simple request (curl)

A simple request returns extracted field names and values:

$
curl "${API_ROOT}/v2/apps/runs/<RUN-ID>/results" \
>
-H "Authorization: Bearer ${API_TOKEN}"`
>
-H "IB-Context: ${IB_CONTEXT}"

Simple request (Python SDK)

1
from aihub import AIHub
2
3
client = AIHub(api_root="<API-ROOT>",
4
               api_key="<API-TOKEN>",
5
               ib_context="<IB-CONTEXT>")
6
results = client.apps.runs.results('<RUN-ID>')

Response (simple request)

1
{
2
  "has_more": false,
3
  "batch_id": "9706",
4
  "files": [
5
    {
6
      "original_file_name": "test.png",
7
      "documents": [
8
        {
9
          "class_name": "Wage And Tax Statement",
10
          "fields": [
11
            {
12
              "value": "123 STREET RD ANYWHERE, USA,12345",
13
              "type": "TEXT",
14
              "field_name": "employers_address_and_ZIP_code"
15
            }
16
          ],
17
          "doc_id": null
18
        }
19
      ]
20
    },
21
    {
22
      "original_file_name": "test2.png",
23
      "documents": [
24
        {
25
          "class_name": "Driver License",
26
          "fields": [
27
            {
28
              "value": "Male",
29
              "type": "TEXT",
30
              "field_name": "sex"
31
            }
32
          ],
33
          "doc_id": null
34
        }
35
      ]
36
    }
37
  ]
38
}

Request with query parameters (curl)

This request includes the include_confidence_scores and include_source_info query parameters. Confidence scores and source information (coordinates) are returned:

$
curl "${API_ROOT}/v2/apps/runs/<RUN-ID>/results?include_confidence_scores=true&include_source_info=true" \
>
  -H "Authorization: Bearer ${API_TOKEN}"`
>
  -H "IB-Context: ${IB_CONTEXT}"\

Request with query parameters (Python SDK)

1
from aihub import AIHub
2
3
client = AIHub(api_root="<API-ROOT>",
4
               api_key="<API-TOKEN>",
5
               ib_context="<IB-CONTEXT>")
6
results = client.apps.runs.results('<RUN-ID>',
7
                                   include_confidence_score=True,
8
                                   include_source_info=True)

Response (request with query parameters)

1
{
2
  "has_more": false,
3
  "batch_id": "9706",
4
  "files": [
5
    {
6
      "original_file_name": "test.png",
7
      "documents": [
8
        {
9
          "class_name": "Wage And Tax Statement",
10
          "fields": [
11
            {
12
              "value": "123 STREET RD ANYWHERE, USA,12345",
13
              "type": "TEXT",
14
              "confidence": {
15
                "model": 0.59005505
16
              },
17
              "source_coordinates": [
18
                {
19
                  "top_x": 36.0,
20
                  "top_y": 181.0,
21
                  "bottom_x": 84.0,
22
                  "bottom_y": 212.0,
23
                  "page_number": 0
24
                },
25
                {
26
                  "top_x": 90.0,
27
                  "top_y": 182.0,
28
                  "bottom_x": 198.0,
29
                  "bottom_y": 211.0,
30
                  "page_number": 0
31
                }
32
              ],
33
              "field_name": "employers_address_and_ZIP_code"
34
            }
35
          ],
36
          "post_processed_paths": [
37
            "instabase-org/orguser/fs/S3 Drive/app-runs/dd97-42cb-8b8e-28a63066887e/4180-8508-b103afb67185/s1_process_files/images/test.png.PNG"
38
          ],
39
          "doc_id": null
40
        }
41
      ]
42
    },
43
    {
44
      "original_file_name": "test2.png",
45
      "documents": [
46
        {
47
          "class_name": "Driver License",
48
          "fields": [
49
            {
50
              "value": "Male",
51
              "type": "TEXT",
52
              "confidence": {
53
                "model": 0.691
54
              },
55
              "source_coordinates": [],
56
              "field_name": "sex"
57
            }
58
          ],
59
          "post_processed_paths": [
60
            "instabase-org/orguser/fs/S3 Drive/app-runs/dd97-42cb-8b8e-28a63066887e/4180-8508-b103afb67185/s1_process_files/images/test2.png.PNG"
61
          ],
62
          "doc_id": null
63
        }
64
      ]
65
    }
66
  ]
67
}

Runtime config

You can use the runtime_config setting to specify key-value pairs to pass into the run at runtime. These values are propagated to downstream processes and can be referenced in validation functions.

For example, if your validation function’s behavior varies based on time of year, you might use runtime_config to pass in the current date, for example:

1
{
2
  "current_date": "06/01/2024",
3
  ...
4
}

Webhook parameters

You can use the webhook_config setting to ensure your application is notified when a run completes. AI Hub POSTs JSON-encoded data of the format below to the webhook endpoint:

$
# body
>
{
>
"status": <string>,
>
"msg": <string>,
>
"job_id": <string>,
>
"input_dir": <string>,
>
"output": <string>
>
}

The response body contains the following fields:

• status: "OK" | "ERROR"

• msg: (optional) Error message. Present only if status is ERROR.

• job_id: A unique identifier for the run.

• input_dir: Input directory.

• output: The full path to the root output folder.

To acknowledge receipt of the event, your endpoint must return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, indicate to AI Hub that you did not receive the event.

If AI Hub does not receive a 2xx HTTP status code, the notification attempt is repeated up to 7 times.

Specifying file paths

When running an app using the v2/apps/runs endpoint, there are two methods to specify the app’s input:

• Batch: Create a batch using the Batches endpoint, upload files from your local filesystem, then use the batch_id parameter to specify the batch. All files in the batch are processed.

• Connected drive: Use the input_dir parameter to specify a file path to an input folder in a connected drive. All files in the input folder are processed.

When specifying a file path in a connected drive, the format varies if you have a community or organization account.

• Community account: /<USER-ID>/my-repo/fs/<DRIVE-NAME>/<FOLDER>/

• Organization account: /<ORGANIZATION-ID>/<WORKSPACE>/fs/<DRIVE-NAME>/<FOLDER>/