License Usage API

Table of Contents

The License Usage API lets you get the usage information for licenses, products, and resources.

In this document, URL_BASE refers to the root URL of your Instabase instance, such as https://www.instabase.com.

Get usage information for all the licenses

Method	Syntax
GET	`URL_BASE/api/v1/license-service/usage`

Description

Get license usage for all licenses/products. The usage is aggregated over the attributes listed in the group_by parameter. You can also filter the returned usage by optional query parameters listed in the Request parameters section.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`group_by`	string	List of attributes to be populated in the response. By default the usage is grouped by IBLicenseID.	UserAccountID, ProductName, ProductVersion, ResourceName, ProductResourceID, AssignmentID, CreditID, SolutionID, SolutionName, SolutionVersion, SolutionOwner
`product_name`	string	Optional. Returns only the usage corresponding to the product as specified in the license.	‘FLOW’, ‘GENERIC_IB_MKTPLACE_SOLN’, ‘GENERIC_CUSTOM_MKTPLACE_SOLN’ or a custom solution name
`resource_name`	string	Optional. Returns only the usage corresponding to the product resource of a license.	‘DC_PAGES’, ‘DCE_PAGES’, ‘DIGITIZED_PAGES’, ‘CLASSIFIED_PAGES’, ‘DOCUMENT_EXTRACTION’
`user_account_id`	string	Optional. Returns the usage of user with given account-id
`job_id`	string	Optional. Returns usage records of job with given job-id
`solution_id`	string	Optional. Returns usage only for a specific deployed solution id
`solution_name`	string	Optional. Returns usage only for a specific deployed solution name
`solution_version`	string	Optional. Returns usage only for a specific deployed solution version
`solution_owner`	string	Optional. Returns usage only for a specific deployed solution owner
`earliest_time`	integer	Optional. 10-digit Unix timestamp. Returns the usage started after this timestamp.	starting timestamp (default value is 0)
`latest_time`	integer	Optional. 10-digit Unix timestamp. Returns all jobs started before this timestamp.	ending timestamp (default is INT_MAX)

Response schema

The response body is a JSON object containing the usage metrics.

Name	Type	Description
`usage_metrics`	array	An array of usage metrics objects

Each usage metrics object contains the following properties:

Name	Type	Description
`ib_license_id`	string	The IB license id.
`product_name`	string	The name of the product as specified in the license
`resource_name`	string	The name of the product resource
`product_resource_id`	string	The id of the product resource
`credit_id`	string	The credit ID corresponds to the credit pool being consumed.
`usage_amount`	string	The amount of usage in the number of pages.
`credit_cost`	string	The amount of credits consumed
`user_account_id`	string	Instabase user account id
`product_version`	string	The version of the product as mentioned in the license
`assignment_id`	string	The license assignment id
`timestamp_in_secs`	string	10-digit Unix timestamp when the usage was recorded
`job_id`	string	The id of the job generated during the job execution request
`tags`	string	Any associated tags
`solution_id`	string	The id of the deployed solution
`solution_name`	string	The name of the deployed solution
`solution_version`	string	The version of the deployed solution
`solution_owner`	string	The owner of the deployed solution

Examples

Request

import requests

product_name = 'FLOW'
url = url_base + f'/api/v1/license-service/usage?group_by=ProductResourceID,ProductName,ResourceName,CreditID,TimestampInSecs,SolutionID,SolutionName&product_name={product_name}'

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

r = requests.get(url, headers=headers)
resp = json.loads(r.content)
print(resp)

Response

{
    "usage_metrics": [
        {
            "ib_license_id": "licenseID",
            "product_name": "FLOW",
            "resource_name": "DC_PAGES",
            "product_resource_id": "5249c2d02ff24d6e8da59380ff8135e0",
            "credit_id": "creditID",
            "timestamp_in_secs": "1686700800",
            "usage_amount": "9",
            "credit_cost": "0",
            "solution_id": "301a9dd8-ec35-4fd6-b2d3-09dd707a49f7",
            "solution_name": "soln-test",
            "user_account_id": "",
            "product_version": "ANY",
            "assignment_id": "",
            "job_id": "",
            "tags": "",
            "solution_version": "",
            "solution_owner": ""
        },
    ]
}

Get usage information for a single license

Method	Syntax
GET	`URL_BASE/api/v1/license-service/usage/<license_ID>`

Description

Get license usage for an individual license. The usage is aggregated over the attributes listed in the group_by parameter. The returned usage can also be filtered by optional query parameters listed in the Request parameters section.

Request parameters

See the Get usage information for all the licenses.

Response schema

See the Get usage information for all the licenses.

Examples

Request

import requests

license_id = 'license-id'
product_name = 'FLOW'
url = url_base + f'/api/v1/license-service/usage/{license_id}?group_by=ProductResourceID,ProductName,ResourceName,CreditID,TimestampInSecs,SolutionID,SolutionName&product_name={product_name}'

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

r = requests.get(url, headers=headers)
resp = json.loads(r.content)
print(resp)

Response

{
    "usage_metrics": [
        {
            "ib_license_id": "licenseID",
            "product_name": "FLOW",
            "resource_name": "DC_PAGES",
            "product_resource_id": "5249c2d02ff24d6e8da59380ff8135e0",
            "credit_id": "creditID",
            "timestamp_in_secs": "1686700800",
            "usage_amount": "9",
            "credit_cost": "0",
            "solution_id": "301a9dd8-ec35-4fd6-b2d3-09dd707a49f7",
            "solution_name": "soln-test",
            "user_account_id": "",
            "product_version": "ANY",
            "assignment_id": "",
            "job_id": "",
            "tags": "",
            "solution_version": "",
            "solution_owner": ""
        },
    ]
}

Get resource usage breakdown

Method	Syntax
GET	`URL_BASE/api/v1/license-service/resource_usage`

Description

Get resource usage breakdown for all the jobs that have been executed in the given time range.

Request parameters

Name	Type	Description	Values
`start_time`	integer	Optional. 10-digit Unix timestamp. Returns the usage for all the jobs that have been completed after this timestamp.	starting timestamp (default value is 0)
`end_time`	integer	Optional. 10-digit Unix timestamp. Returns the usage for all the jobs that have been completed before this timestamp.	ending timestamp (default is INT_MAX)

Response schema

The response body is a JSON object containing the license resource usages.

Name	Type	Description
`license_resource_usages`	object	An object containing the usage metrics for different license resources.

Based on the usage, the license_resource_usages object might contain the following:

Name	Type	Description
`DIGITIZED_PAGES`	string	Number of pages run through the process file step.
`CLASSIFIED_PAGES`	string	Number of pages run through the classifier step, with multiple counts if the classifier is executed more than once.
`DOCUMENT_EXTRACTION`	string	Number of pages run through refiner, with multiple counts if the refiner is executed more than once.

Note that this API response doesn’t include usage for Flow V2 jobs, Flow V2 license usage natively supports resource breakdown.

Info

This API request might take some time to process, especially for a large number of job records. To handle large time windows efficiently, it’s recommended to use a script that runs and accumulates the usage for smaller time periods.

Examples

Request

import requests

start_time = '1689000000000000000'
end_time = '1689369930844472036'
url = url_base + f'/api/v1/license-service/resource_usage?start_time={start_time},end_time={end_time}'

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

r = requests.get(url, headers=headers)
resp = json.loads(r.content)
print(resp)

Response

{
    "license_resource_usages": {
        "CLASSIFIED_PAGES": "817",
        "DIGITIZED_PAGES": "1704",
        "DOCUMENT_EXTRACTION": "229"
    }
}