Skip to content

Provider

Endpoints for data providers to view dashboard summaries, per-dataset analytics, and payout statements.

Provider Dashboard

Get an overview of the authenticated provider's datasets, objects, and storage usage.

GET /v1/provider/dashboard

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

Scope: usage:read

Request

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

import requests

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

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

Parameters

No parameters required.

Response

{
  "data": {
    "total_datasets": 5,
    "total_objects": 1247,
    "total_storage_bytes": 2147483648,
    "objects_pending_review": 12,
    "objects_approved": 1220,
    "objects_rejected": 15
  },
  "request_id": "req_prv001",
  "timestamp": "2026-04-05T10:00:00Z"
}

Response Fields

Field Type Description
total_datasets integer Total number of datasets owned by the tenant.
total_objects integer Total number of objects across all datasets.
total_storage_bytes integer Total storage used across all datasets in bytes.
objects_pending_review integer Number of objects awaiting admin review.
objects_approved integer Number of objects that have been approved.
objects_rejected integer Number of objects that have been rejected.

Dataset Analytics

Get analytics for a specific dataset owned by the authenticated tenant.

GET /v1/provider/datasets/{id}/analytics

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

Scope: usage:read

Request

curl -X GET https://api.ipto.ai/v1/provider/datasets/dset_a1b2c3d4e5f6/analytics \
  -H "Authorization: Bearer {token}"

import requests

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

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

Parameters

Field Type Required Description
id string Yes The dataset ID (path parameter).

Response

{
  "data": {
    "dataset_id": "dset_a1b2c3d4e5f6",
    "dataset_name": "AP Invoices 2025",
    "object_count": 142,
    "active_object_count": 138,
    "storage_bytes": 58720256
  },
  "request_id": "req_prv002",
  "timestamp": "2026-04-05T10:01:00Z"
}

Response Fields

Field Type Description
dataset_id string Unique identifier for the dataset.
dataset_name string Human-readable name of the dataset.
object_count integer Total number of objects in the dataset.
active_object_count integer Number of objects that are approved and indexed.
storage_bytes integer Total storage used by the dataset in bytes.

List Payouts

List payout statements for the authenticated provider tenant.

GET /v1/provider/payouts

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

Scope: billing:read

Request

curl -X GET "https://api.ipto.ai/v1/provider/payouts?limit=10" \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/provider/payouts",
    headers={"Authorization": "Bearer {token}"},
    params={"limit": 10},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/provider/payouts?limit=10",
  {
    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 payout statements to return. Default: 20.

Response

{
  "data": {
    "payouts": [
      {
        "payout_statement_id": "pst_a1b2c3d4e5f6",
        "billing_period_start": "2026-03-01T00:00:00Z",
        "billing_period_end": "2026-03-31T23:59:59Z",
        "gross_revenue": 1250.00,
        "seller_earnings": 875.00,
        "held_amount": 125.00,
        "released_amount": 750.00,
        "currency": "USD",
        "status": "paid",
        "created_at": "2026-04-01T06:00:00Z"
      },
      {
        "payout_statement_id": "pst_g7h8i9j0k1l2",
        "billing_period_start": "2026-02-01T00:00:00Z",
        "billing_period_end": "2026-02-28T23:59:59Z",
        "gross_revenue": 980.50,
        "seller_earnings": 686.35,
        "held_amount": 98.05,
        "released_amount": 588.30,
        "currency": "USD",
        "status": "paid",
        "created_at": "2026-03-01T06:00:00Z"
      }
    ],
    "total": 2
  },
  "request_id": "req_prv003",
  "timestamp": "2026-04-05T10:02:00Z"
}

Response Fields

Field Type Description
payouts Payout[] Array of payout statement objects.
total integer Total number of payout statements.

Payout fields:

Field Type Description
payout_statement_id string Unique identifier for the payout statement.
billing_period_start string ISO 8601 start of the billing period.
billing_period_end string ISO 8601 end of the billing period.
gross_revenue number Total revenue generated during the billing period.
seller_earnings number Net earnings after platform fees.
held_amount number Amount held in reserve (e.g., for dispute resolution).
released_amount number Amount released to the provider.
currency string ISO 4217 currency code (e.g., USD).
status string Payout status (e.g., pending, processing, paid, failed).
created_at string ISO 8601 timestamp when the statement was generated.