Using Postman with Observability APIs¶

Note: To use the Observability APIs, set the environment variable USE_AIR_API_V2_BASE_URL=True in your SDK environment. Queries to the observability endpoints will then use https://api-prod-k8s.airefinery.accenture.com/. This feature is available starting from SDK version 1.25.0. This is a temporary setup, and we will transition to the regular URL soon.

Overview¶

This guide walks you through setting up and using Postman to interact with the AIRefinery Observability APIs. These APIs provide access to logs, metrics, and traces collected via OpenTelemetry. You can utilize the observability endpoints through Postman to monitor application performance, debug issues, and gain insights into your AIRefinery workloads.

Goals¶

By the end of this tutorial, you will:

Set up a Postman collection for AIRefinery Observability APIs with proper authentication
Configure environment variables for reusable requests across different environments
Query logs from Loki to troubleshoot application issues and monitor service health
Retrieve metrics from Prometheus to analyze inference performance, agent operations, and session analytics
Access traces from Tempo to visualize service dependencies and debug cross-service interactions
Understand how to filter observability data by organization and project scope

Prerequisites¶

Postman installed on your system
A valid AIRefinery API key
Your organization ID and project name (if applicable)

Initial Setup¶

Step 1: Create a New Collection¶

Open Postman
Click on Collections in the left sidebar
Click + New Collection
Name it AIRefinery Observability APIs
Add a description (optional): OpenTelemetry-based observability endpoints for logs, metrics, and traces

Step 2: Set the Base URL¶

Click on your collection name
Go to the Variables tab
Add a new variable:
Variable: base_url
Initial Value: http://api-prod-k8s.airefinery.accenture.com (or your API endpoint)
Current Value: http://api-prod-k8s.airefinery.accenture.com
Click Save

Setting Up Environment Variables¶

Using environment variables makes your requests reusable and easier to manage.

Create an Environment¶

Click on Environments in the left sidebar
Click + Create Environment
Name it AIRefinery Development (or as appropriate)

Add the Following Variables¶

Variable	Initial Value	Description
`base_url`	`http://api-prod-k8s.airefinery.accenture.com`	API base URL
`api_key`	`your-api-key-here`	Your API key
`organization_id`	`org-123`	Your organization ID
`project_name`	`project-x`	Your project name

Click Save
Select this environment from the dropdown in the top-right corner

Configuring Authentication¶

Open a specific request
Go to the Headers tab
Add a new header:
Key: Authorization
Value: Bearer {{api_key}}

Testing the APIs¶

1. Query Logs (POST /observability/logs)¶

a. Create the Request

Click Add request in your collection
Name it Get Logs
Set method to POST
URL: http://api-prod-k8s.airefinery.accenture.com/observability/logs

b. Configure Headers

Add these headers:

Key: Content-Type, Value: application/json
Key: Authorization, Value: {{api_key}} (if not using collection-level auth)
Key: sdk_version, Value: {{sdk_version}} (sdk version higher than 1.13.0)

c. Configure Body

Select Body tab
Choose raw and JSON format
Add the request body:

{
  "organization_id": "{{organization_id}}",
  "time_window": "1h",
  "limit": 100
}

d. Example Variations

Get logs for a specific project:

{
  "organization_id": "{{organization_id}}",
  "project_name": "{{project_name}}",
  "time_window": "30m",
  "limit": 100
}

e. Send the Request

Click the Send button and view the response in the lower panel.

Example Logs — An example of retrieved logs

2. Query Metrics (POST /observability/metrics)¶

a. Create the Request

Add a new request to your collection
Name it Get Metrics
Set method to POST
URL: http://api-prod-k8s.airefinery.accenture.com/observability/metrics

b. Configure Headers

Same as logs request above.

c. Configure Body

Token consumption metrics:

{
  "metric": "token_consumption",
  "organization_id": "{{organization_id}}",
  "time_window": "1h"
}

Agent task metrics:

{
  "metric": "agent_task_total",
  "organization_id": "{{organization_id}}",
  "project_name": "{{project_name}}",
  "time_window": "30m"
}

Inference metrics with model filter:

{
  "metric": "inference_requests_total",
  "organization_id": "{{organization_id}}",
  "model_key": "gpt-4",
  "time_window": "5m"
}

Agent metrics with agent filter:

{
  "metric": "agent_task_total",
  "organization_id": "{{organization_id}}",
  "agent_name": "orchestrator",
  "time_window": "30m"
}

3. Query Traces (POST /observability/traces)¶

a. Create the Request

Add a new request to your collection
Name it Get Traces
Set method to POST
URL: http://api-prod-k8s.airefinery.accenture.com/observability/traces

b. Configure Headers

Same as logs request above.

c. Configure Body

Organization-level inference traces:

{
  "trace": "inference_traces",
  "organization_id": "{{organization_id}}",
  "time_window": "1h"
}

Project-level distiller traces:

{
  "trace": "distiller_traces",
  "organization_id": "{{organization_id}}",
  "project_name": "{{project_name}}",
  "time_window": "30m"
}

Get specific trace by ID:

{
  "trace": "inference_traces",
  "organization_id": "{{organization_id}}",
  "trace_id": "abc123def456"
}

Search without detailed trace data:

{
  "trace": "inference_traces",
  "organization_id": "{{organization_id}}",
  "detail": false,
  "limit": 50
}

Example Collections¶

1. Complete Collection Structure

Your Postman collection should look like this:

📁 AIRefinery Observability APIs
├── 📄 Get Logs - Organization
├── 📄 Get Logs - Project
├── 📄 Get Logs - Service Specific
├── 📄 Get Metrics - Token Consumption
├── 📄 Get Metrics - Agent Tasks
├── 📄 Get Metrics - Inference Requests
├── 📄 Get Traces - Inference
├── 📄 Get Traces - Distiller
└── 📄 Get Traces - By ID

2. Importing a Pre-configured Collection

If you have a JSON collection file, you can import it:

Click Import in Postman
Select File or drag and drop the JSON file
Click Import

3. Save Example Responses

After getting a successful response:

Click Save Response dropdown
Select Save as example
Name the example appropriately

This helps document expected responses for your team.

4. Common Time Window Formats

Valid time window values:

Minutes: 5m, 15m, 30m
Hours: 1h, 6h, 12h, 24h
Days: 1d, 7d, 30d

5. Handling Errors

Common error responses:

401 Unauthorized:

Check your api key is valid and properly set
Ensure Authorization header is included

400 Bad Request:

Verify all required parameters are included
Check JSON syntax is correct
Ensure parameter values match expected types

500 Internal Server Error:

Check API server logs
Verify time window format is correct

6. Export and Share

To share your collection with team members:

Click the ... menu on your collection
Select Export
Choose Collection v2.1 format
Share the exported JSON file

7. Use Collection Runner

To test multiple requests sequentially:

Right-click on your collection
Select Run collection
Select which requests to run
Click Run AIRefinery Observability APIs

8. Monitor API Performance

Use Postman's Monitor feature to:

Schedule automated API tests
Track API performance over time
Get alerts when APIs fail

Advanced Features¶

1. Using Dynamic Variables

Postman provides dynamic variables that can be useful:

{{$timestamp}} - Current Unix timestamp

Example:

{
  "organization_id": "{{organization_id}}",
  "time_window": "1h",
}

2. Chaining Requests

Extract data from one response and use it in another request:

In the Tests tab of your first request:

var jsonData = pm.response.json();
pm.environment.set("trace_id", jsonData.traces[0].traceID);

Then use {{trace_id}} in subsequent requests.

3. Using Postman Console

View detailed request/response information:

Click Console at the bottom of Postman
Send a request
View raw HTTP headers, request body, response body, and timing details