AI Agent Queries & History Retrieval in Postman

In this Article

• Overview
• Step 1: Generate OAuth2 Access Token
• Step 2: Execute an AI Agent Query
• Step 3: Retrieve AI Agent Question History(Legacy)
• Step 4: Questions History (V1)
• FAQ

Overview

This document provides a step-by-step guide to:

1. Generating an OAuth2 Access Token
2. Executing an AI Agent Query
3. Retrieving AI Agent Question History

All steps are performed using Postman.

Please refer to the DvSum API Reference Guide for comprehensive API documentation.

Prerequisites

Before you begin, ensure you have:

• Client ID 
• Client Secret

Please refer to the article for detailed instructions on how to retrieve the Client ID and Client Secret.

• Postman installed
• Access to: https://apis.dvsum.ai

Step 1: Generate OAuth2 Access Token

All API requests require a Bearer Token for authentication.

Endpoint

POST https://auth.dvsum.ai/oauth2/token

Configure in Postman

Set HTTP Method

Set the request method to: POST

Option 1: Using Postman Authorization Tab (Recommended)

Authorization Configuration

1. Navigate to the Authorization tab.
2. Select Basic Auth.
3. Enter the following:
   • Username → Client ID
   • Password → Client Secret

Headers

Add the following headers:

Option 2: Using Manual Authorization Header

If not using the Authorization tab:

Headers

How to Generate the Authorization Header

Use the Client ID and Client Secret you generated earlier to obtain an access token.

1. Combine your Client ID and Secret in the format:
   client_id:client_secret
2. Convert this string into Base64 encoding
   1. Once generated, copy the encoded value and paste it into the Authorization header in Postman as shown below:

Authorization: Basic <base64_encoded_value>

4. Configure Body

1. Select Body tab.
2. Choose x-www-form-urlencoded.
3. Add:

5. Send Request

Click Send.

Sample Response

{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Important

Copy the access_token.

This token must be included in all subsequent requests as a Bearer Token.

Step 2: Execute an AI Agent Query

This endpoint allows you to send a question to the AI Agent for analysis.

Prerequisite

Before executing an AI Agent query, you must establish a WebSocket connection.
The AI Agent uses WebSocket communication to process and return query results.

Establish WebSocket Connection in Postman

1. Create New WebSocket Request

1. Open Postman.
2. Select WebSocket Request.

2. Enter WebSocket URL

wss://17ew4pfncd.execute-api.us-west-2.amazonaws.com/prod

4. Connect

Click Connect to establish the WebSocket session.

Then Click on Send. The WebSocket server will respond with a message containing your unique ID. You will need this ID for the next step.

Endpoint

POST https://apis.dvsum.ai/<ai-agent-query-endpoint>

(Replace <ai-agent-query-endpoint> with the actual AI Agent query endpoint configured in your environment.)

Configure in Postman

1. Method

Set the request method to: POST

2. Headers

3. Body (Raw JSON)

Select: Body → raw → JSON

Example request:

{
  "analysis_id": 50029180,(Agent ID)
  "connection_id": "Yh1JOfIwvHcCElQ=",
  "tool_id": "",
  "audience_type": "CUSTOMER_FACING",
  "response_type": "JSON",
  "messages": [
    {
      "human_message": "analyze customer 50137438"
    }
  ],
  "properties": {
            "gen_interaction_id": 12000001,
    "user_name": "<username>",
    "api_query_id": "10000026"
        }
}

Audience Type Values:

The audience_type parameter determines how the AI response is formatted and presented.
It does not change the underlying data analysis or workflow execution.

4. Send Request

Click Send.

Sample Response

{
    "status": "Execution is in progress..."
}

Upon a successful request, the API returns a 200 status code to initiate the Co-pilot execution. All further communication between the frontend and backend occurs via the WebSocket channel.

Step 3: Retrieve AI Agent Question History (Legacy)

This endpoint retrieves previously submitted AI Agent queries.

Endpoint

GET https://apis.dvsum.ai/<ai-agent-history-endpoint>

Configure in Postman

1. Method

GET

2. Headers

3. Query Parameters

• If export-as-file=true, it returns a JSON object with a pre-signed S3 URL for a CSV download.

• If export-as-file=false (or omitted), it returns a JSON array of the history records.

Step 4: Questions History (V1)

This endpoint retrieves the history of questions for a specific agent using the new nested schema structure.

It supports:

• Date range filtering

• Pagination

• CSV export

• Default lookback window

Endpoint

GET https://apis.dvsum.ai/data-analysis/v1/{agent-id}/questions-history

Configure in Postman

1. Method

GET

2. Headers

3. Query Parameters

4. Result:

For more details on API Access and Authentication Management please refer article: DvSum API Access and Authentication Management

FAQ: 

How long does it typically take to set up and test the AI Agent API?
In our experience, the initial setup typically takes 1–2 hours for someone familiar with APIs and Postman.

Most of the setup time is spent on:

• Retrieving the Client ID and Client Secret

• Generating the OAuth2 access token correctly

• Establishing the WebSocket connection

• Validating the correct analysis_id and connection_id

Once configured successfully, subsequent API calls take only a 10-15 minutes to execute.

Why is my AI Agent request returning “Execution is in progress…” but no final result?
This is expected behavior.

The REST API call only initiates execution. The AI Agent delivers results through the WebSocket connection, not through the same POST response.

Common setup oversight:

• WebSocket not connected

• Incorrect connection_id

• WebSocket session timed out before execution completed

Ensuring an active WebSocket connection before sending the POST request resolves this.

Is prior API experience required to use this guide?
Basic knowledge of the following is helpful but not mandatory:

• HTTP methods (GET, POST)

• Headers and request body structure

• Bearer token authentication

The guide provides all required configuration details, allowing users to complete the setup even without extensive API experience.

What should be done if a 401 Unauthorized error is received?
Common causes:

• Expired access token

• Incorrect Client ID or Client Secret

• Incorrect Authorization header format

• Missing Bearer prefix before the token

Resolution steps:

• Regenerate the OAuth2 access token

• Verify that the header is correctly formatted: Authorization: Bearer <access_token>

How long is the access token valid?
This typically indicates that the token is valid for 3600 seconds (1 hour).

After expiration, a new access token must be generated.

Can the same access token be reused for multiple API calls?
Yes. The same access token can be reused for multiple API calls until it expires.