Skip to content

Buyer

Endpoints for data buyers to view dashboard summaries, search activity, dataset access history, and spend analytics.

Buyer Dashboard

Get an overview of the authenticated buyer's API key usage.

GET /v1/buyer/dashboard

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: usage:read

Request

curl -X GET https://api.ipto.ai/v1/buyer/dashboard \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/buyer/dashboard",
    headers={"Authorization": "Bearer {token}"},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/buyer/dashboard",
  {
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters

No parameters required.

Response

{
  "data": {
    "api_key_count": 4,
    "active_api_key_count": 3
  },
  "request_id": "req_buy001",
  "timestamp": "2026-04-05T10:00:00Z"
}

Response Fields

Field Type Description
api_key_count integer Total number of API keys owned by the tenant.
active_api_key_count integer Number of API keys that are currently active (not revoked).

List Search Activity

Retrieve search history for the authenticated tenant's agents and API keys.

GET /v1/agent/activity/searches

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: usage:read

Request

curl -X GET "https://api.ipto.ai/v1/agent/activity/searches?limit=20" \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/agent/activity/searches",
    headers={"Authorization": "Bearer {token}"},
    params={"limit": 20},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/agent/activity/searches?limit=20",
  {
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters

Field Type Required Description
cursor string No Opaque pagination cursor from a previous response.
limit integer No Maximum number of search records to return. Default: 20.

Response

{
  "data": {
    "searches": [
      {
        "search_activity_id": "sa_a1b2c3d4e5f6",
        "query_text": "invoice showing VAT dispute with Acme in March",
        "dataset_ids": ["dset_a1b2c3d4e5f6", "dset_g7h8i9j0k1l2"],
        "result_count": 15,
        "charged_amount": 0.45,
        "currency": "USD",
        "occurred_at": "2026-04-05T09:30:00Z"
      },
      {
        "search_activity_id": "sa_m7n8o9p0q1r2",
        "query_text": "quarterly financial report 2025",
        "dataset_ids": ["dset_a1b2c3d4e5f6"],
        "result_count": 8,
        "charged_amount": 0.24,
        "currency": "USD",
        "occurred_at": "2026-04-05T09:15:00Z"
      }
    ],
    "total": 2
  },
  "request_id": "req_buy002",
  "timestamp": "2026-04-05T10:00:00Z"
}

Response Fields

Field Type Description
searches SearchActivity[] Array of search activity records.
total integer Total number of search activity records matching the query.

SearchActivity fields:

Field Type Description
search_activity_id string Unique identifier for the search activity record.
query_text string The search query that was executed.
dataset_ids string[] List of dataset IDs that were searched.
result_count integer Number of results returned.
charged_amount number Amount charged for this search.
currency string ISO 4217 currency code (e.g., USD).
occurred_at string ISO 8601 timestamp when the search was executed.

List Access Activity

Retrieve dataset access history for the authenticated tenant's agents and API keys.

GET /v1/agent/activity/accesses

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: usage:read

Request

curl -X GET "https://api.ipto.ai/v1/agent/activity/accesses?limit=20" \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/agent/activity/accesses",
    headers={"Authorization": "Bearer {token}"},
    params={"limit": 20},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/agent/activity/accesses?limit=20",
  {
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters

Field Type Required Description
cursor string No Opaque pagination cursor from a previous response.
limit integer No Maximum number of access records to return. Default: 20.

Response

{
  "data": {
    "accesses": [
      {
        "dataset_id": "dset_a1b2c3d4e5f6",
        "dataset_name": "AP Invoices 2025",
        "access_count": 47,
        "last_accessed_at": "2026-04-05T09:30:00Z"
      },
      {
        "dataset_id": "dset_g7h8i9j0k1l2",
        "dataset_name": "Legal Contracts Archive",
        "access_count": 12,
        "last_accessed_at": "2026-04-04T16:45:00Z"
      }
    ],
    "total": 2
  },
  "request_id": "req_buy003",
  "timestamp": "2026-04-05T10:00:00Z"
}

Response Fields

Field Type Description
accesses AccessActivity[] Array of dataset access records.
total integer Total number of datasets accessed.

AccessActivity fields:

Field Type Description
dataset_id string Unique identifier for the dataset.
dataset_name string Human-readable name of the dataset.
access_count integer Total number of times the dataset was accessed.
last_accessed_at string ISO 8601 timestamp of the most recent access.

Get Spend Summary

Retrieve a spend summary for the authenticated buyer tenant.

GET /v1/agent/spend

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: billing:read

Request

curl -X GET https://api.ipto.ai/v1/agent/spend \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/agent/spend",
    headers={"Authorization": "Bearer {token}"},
)
data = response.json()

const response = await fetch("https://api.ipto.ai/v1/agent/spend", {
  headers: { Authorization: "Bearer {token}" },
});
const data = await response.json();

Parameters

No parameters required.

Response

{
  "data": {
    "total_spend": 125.67,
    "currency": "USD",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "search_spend": 98.42,
    "retrieval_spend": 27.25
  },
  "request_id": "req_buy004",
  "timestamp": "2026-04-05T10:00:00Z"
}

Response Fields

Field Type Description
total_spend number Total amount spent during the current billing period.
currency string ISO 4217 currency code (e.g., USD).
period_start string ISO 8601 start of the current billing period.
period_end string ISO 8601 end of the current billing period.
search_spend number Amount spent on search queries.
retrieval_spend number Amount spent on data retrieval and downloads.