Get Usage

Endpoint Overview

GET /api/v1/sureparser/get-usage

Description

The Get Usage API endpoint provides a summary of overall usage statistics within the Surepass SureParse platform. It returns key metrics such as the total number of parsed pages, processor runs, completed executions, and failed executions. This endpoint is essential for monitoring platform activity, supporting operational analytics, and enabling data-driven decision-making for resource allocation and process optimization.

Key Benefits

Instantly access high-level usage statistics for the entire platform.

Supports operational monitoring and capacity planning.

Enables proactive identification of processing trends and issues.

Facilitates compliance and reporting with accurate usage data.

Use Cases

Financial Services

Healthcare

Logistics

Monitor overall document processing activity for compliance and audits.

Track platform usage for billing and resource allocation.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT)
Content-Type	No	Optional for GET requests

Query Parameters

None required for this endpoint.

Example Request

{}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains usage statistics
├─ parsed_pages	int	Total number of pages parsed
├─ processor_runs	int	Total number of processor runs
├─ completed_count	int	Number of completed executions
├─ failed_count	int	Number of failed executions
status_code	int	HTTP status code (e.g., 200 for success)
success	bool	Indicates if the request was successful
message	string	Human-readable status message
message_code	string	Machine-readable status code

Example Successful Response

{
  "data": {
    "parsed_pages": 25,
    "processor_runs": 10,
    "completed_count": 9,
    "failed_count": 1
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Authentication Error

Internal Server Error

{
  "data": null,
  "status_code": 401,
  "success": false,
  "message": "Unauthorized",
  "message_code": "unauthorized"
}

The request is missing a valid Bearer token or the token is invalid/expired.

Integration Best Practices

Security Recommendations

Always use HTTPS for all API requests to protect sensitive data in transit.

Store JWT tokens securely and rotate them regularly.

Restrict access to usage statistics to authorized users only.

User Experience Guidelines

Display usage statistics in a clear, actionable format for users.

Handle and display error messages if usage data cannot be retrieved.

Code Samples

cURL

Python

Node.js

Related APIs

Get Usage (with filters): Retrieve usage statistics for a specific processor or folder.

Execution History (GET): Retrieve a paginated list of all processor execution records.

Processor Status: Get the current status and results of a processor execution.

Compliance and Legal Considerations

Ensure that access to usage statistics complies with your organization’s data privacy and retention policies. Only authorized users should be allowed to view usage data, and all access should be logged for audit purposes.

This documentation provides a complete, implementation-focused guide for integrating with the Get Usage API endpoint. For further support, consult the Surepass developer portal or contact your Surepass technical representative.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

{ "data": { "parsed_pages": 150, "processor_runs": 25, "document_processed": 75, "completed_count": 23, "failed_count": 2 }, "status_code": 200, "message": "Success", "success": true }

Get Usage

Get Usage#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Get Usage

Description

Use Cases

Technical Implementation

Request Headers

Query Parameters

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples