Provider Analytics¶

As a data provider on IPTO, you have access to analytics that show how your datasets are performing in the marketplace. This guide covers the provider dashboard, per-dataset analytics, and payout statements.

Overview¶

Provider analytics answer three questions:

1. How is my data being used? -- Search volume, top keywords, and ranking behavior across your datasets.
2. How much revenue is my data generating? -- Usage-based revenue breakdowns and trends.
3. When will I get paid? -- Payout statements with status tracking through the settlement lifecycle.

The analytics are available through both the IPTO console and the REST API.

Viewing the provider dashboard¶

The provider dashboard returns a high-level summary of analytics across all datasets you own. Use query parameters to filter by dataset or date range.

# All datasets, last 30 days
curl -X GET "https://api.ipto.ai/v1/provider/analytics" \
  -H "Authorization: Bearer $TOKEN"

# Specific dataset, custom date range
curl -X GET "https://api.ipto.ai/v1/provider/analytics?dataset_id=dset_abc123&from=2026-03-01T00:00:00Z&to=2026-03-31T23:59:59Z" \
  -H "Authorization: Bearer $TOKEN"

import requests

BASE = "https://api.ipto.ai"
headers = {"Authorization": f"Bearer {token}"}

# All datasets
resp = requests.get(
    f"{BASE}/v1/provider/analytics",
    headers=headers,
)
resp.raise_for_status()
dashboard = resp.json()["data"]

print("Top keywords:", dashboard["top_keywords"])
print("Usage summary:", dashboard["usage_summary"])
print("Revenue summary:", dashboard["revenue_summary"])

# Filtered by dataset and date range
resp = requests.get(
    f"{BASE}/v1/provider/analytics",
    headers=headers,
    params={
        "dataset_id": "dset_abc123",
        "from": "2026-03-01T00:00:00Z",
        "to": "2026-03-31T23:59:59Z",
    },
)
filtered = resp.json()["data"]

const BASE = "https://api.ipto.ai";
const headers = { Authorization: `Bearer ${token}` };

// All datasets
const dashRes = await fetch(`${BASE}/v1/provider/analytics`, { headers });
const dashboard = (await dashRes.json()).data;

console.log("Top keywords:", dashboard.top_keywords);
console.log("Usage summary:", dashboard.usage_summary);
console.log("Revenue summary:", dashboard.revenue_summary);

// Filtered by dataset and date range
const params = new URLSearchParams({
  dataset_id: "dset_abc123",
  from: "2026-03-01T00:00:00Z",
  to: "2026-03-31T23:59:59Z",
});
const filteredRes = await fetch(
  `${BASE}/v1/provider/analytics?${params}`,
  { headers }
);
const filtered = (await filteredRes.json()).data;

Dashboard response sections¶

The dashboard returns four sections:

top_keywords -- The most frequent search terms that matched your datasets.

{
  "top_keywords": [
    {"keyword": "VAT dispute", "count": 342},
    {"keyword": "vendor invoice", "count": 287},
    {"keyword": "quarterly revenue", "count": 156}
  ]
}

ranking_summary -- How your datasets rank in search results.

{
  "ranking_summary": {
    "total_impressions": 12450,
    "avg_rank": 3.2,
    "top_3_rate": 0.68
  }
}

usage_summary -- Aggregate usage metrics.

{
  "usage_summary": {
    "total_retrievals": 8920,
    "total_citations": 1205,
    "total_downloads": 340,
    "total_outcome_events": 12
  }
}

revenue_summary -- Revenue from marketplace activity.

{
  "revenue_summary": {
    "gross_revenue": 4250.00,
    "currency": "USD",
    "revenue_by_type": {
      "retrieval": 3800.00,
      "citation": 280.00,
      "download": 150.00,
      "outcome": 20.00
    }
  }
}

Per-dataset analytics¶

Drill into a specific dataset to see its individual performance. Pass the dataset ID as a path parameter.

curl -X GET "https://api.ipto.ai/v1/provider/analytics?dataset_id=dset_abc123" \
  -H "Authorization: Bearer $TOKEN"

resp = requests.get(
    f"{BASE}/v1/provider/analytics",
    headers=headers,
    params={"dataset_id": "dset_abc123"},
)
resp.raise_for_status()
dataset_analytics = resp.json()["data"]

print(f"Retrievals: {dataset_analytics['usage_summary']['total_retrievals']}")
print(f"Revenue: {dataset_analytics['revenue_summary']['gross_revenue']}")
print(f"Top keywords: {dataset_analytics['top_keywords'][:5]}")

const dsParams = new URLSearchParams({ dataset_id: "dset_abc123" });
const dsRes = await fetch(
  `${BASE}/v1/provider/analytics?${dsParams}`,
  { headers }
);
const dsAnalytics = (await dsRes.json()).data;

console.log(`Retrievals: ${dsAnalytics.usage_summary.total_retrievals}`);
console.log(`Revenue: ${dsAnalytics.revenue_summary.gross_revenue}`);

Use per-dataset analytics to compare the performance of different datasets and understand which content is driving the most value.

Understanding payout statements¶

Payout statements summarize what you are owed for a billing period. They include gross revenue, your earnings share, any held amounts, and the current payout status.

# List all payouts
curl -X GET "https://api.ipto.ai/v1/provider/payouts" \
  -H "Authorization: Bearer $TOKEN"

# Filter by status
curl -X GET "https://api.ipto.ai/v1/provider/payouts?status=pending" \
  -H "Authorization: Bearer $TOKEN"

# List all payouts
resp = requests.get(
    f"{BASE}/v1/provider/payouts",
    headers=headers,
)
resp.raise_for_status()
payouts = resp.json()["data"]

for payout in payouts:
    print(
        f"Period: {payout['billing_period_start']} - {payout['billing_period_end']}  "
        f"Gross: {payout['gross_revenue']}  "
        f"Earnings: {payout['seller_earnings']}  "
        f"Status: {payout['status']}"
    )

# Filter by status
resp = requests.get(
    f"{BASE}/v1/provider/payouts",
    headers=headers,
    params={"status": "pending"},
)
pending = resp.json()["data"]

// List all payouts
const payRes = await fetch(`${BASE}/v1/provider/payouts`, { headers });
const payouts = (await payRes.json()).data;

for (const payout of payouts) {
  console.log(
    `Period: ${payout.billing_period_start} - ${payout.billing_period_end}  ` +
    `Gross: ${payout.gross_revenue}  ` +
    `Earnings: ${payout.seller_earnings}  ` +
    `Status: ${payout.status}`
  );
}

// Filter by status
const pendingRes = await fetch(
  `${BASE}/v1/provider/payouts?status=pending`,
  { headers }
);
const pending = (await pendingRes.json()).data;

Payout response example¶

{
  "data": [
    {
      "payout_statement_id": "pay_stmt_001",
      "tenant_id": "ten_seller_001",
      "billing_period_start": "2026-03-01T00:00:00Z",
      "billing_period_end": "2026-03-31T23:59:59Z",
      "gross_revenue": 4250.00,
      "seller_earnings": 3187.50,
      "held_amount": 0.00,
      "released_amount": 3187.50,
      "status": "approved",
      "created_at": "2026-04-01T06:00:00Z"
    }
  ],
  "request_id": "req_030",
  "timestamp": "2026-04-05T12:00:00Z"
}

Pagination¶

Payout lists support cursor-based pagination. Pass cursor and limit as query parameters.

curl -X GET "https://api.ipto.ai/v1/provider/payouts?limit=10&cursor=eyJwYWdlIjoy..." \
  -H "Authorization: Bearer $TOKEN"

Payout status explanations¶

Each payout statement has a status that tracks its progress through the settlement lifecycle.

stateDiagram-v2
    [*] --> pending
    pending --> approved
    pending --> held
    approved --> paid
    approved --> held
    held --> approved
    held --> reversed
    paid --> reversed
    paid --> [*]
    reversed --> [*]

Understanding the revenue flow¶

The provider revenue share is calculated from rated usage revenue:

seller_payout = gross_metered_revenue - refunds_and_reversals - held_amount
seller_earnings = revenue_share_rate x seller_payout

The platform retains the residual after revenue share and adjustments. The revenue share rate is determined by your agreement and plan tier.

Revenue comes from four event types:

Next steps¶

• Uploading Data -- Add more content to your datasets to increase marketplace visibility.
• Managing API Keys -- Create keys for automated analytics monitoring.
• Searching Data -- Understand the buyer experience to optimize your dataset descriptions and content.