Reports API

Overview

The Reports API provides programmatic access to Pond3r’s automated crypto intelligence reports. Use this API to:

Create scheduled reports using natural language prompts
List and discover available reports
Access historical report executions
Retrieve report content in both markdown and structured JSON formats

All API endpoints require authentication via API key in the x-api-key header.

Endpoints

Create Report

POST /v1/api/reports - Create a new scheduled report

const response = await axios.post('https://api.pond3r.xyz/v1/api/reports', {
  prompt: 'Track new tokens on Uniswap with less than $500K market cap and rising liquidity',
  datasetId: 'uuid-of-dataset',  // Required: ID from dataset catalog
  scheduleFrequency: 'on_demand', // Required: 'daily', 'weekly', 'monthly', or 'on_demand' (default: 'on_demand')
  recipients: ['user@example.com'], // Optional: Array of email addresses (can be omitted for API-only reports)
  deliveryApiRetention: true,     // Optional: Enable API access to executions (default: false)
  emailEnabled: true,             // Optional: Send email notifications (default: true)
  isPublic: false,                // Optional: Make report publicly accessible (default: false)
  workflowType: 'ON_DEMAND',      // Optional: 'SCHEDULED' or 'ON_DEMAND' (default: 'ON_DEMAND')
  deliverySubject: 'Daily Token Report', // Optional: Custom email subject
  refId: 'my-system-ref-123'      // Optional: Your internal reference ID for this report
}, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "id": "uuid",
  "prompt": "Track new tokens on Uniswap with less than $500K market cap and rising liquidity",
  "datasetId": "uuid-of-dataset",
  "scheduleFrequency": "on_demand",
  "deliveryApiRetention": true,
  "emailEnabled": true,
  "isPublic": false,
  "active": true,
  "status": "PENDING", // or "GENERATING", "COMPLETED", "FAILED"
  "workflowType": "ON_DEMAND",
  "refId": "my-system-ref-123",
  "createdAt": "2024-03-24T09:00:00Z",
  "updatedAt": "2024-03-24T09:00:00Z",
  "recipients": [
    {
      "id": "recipient-uuid",
      "email": "user@example.com"
    }
  ],
  "dataset": {
    "id": "uuid",
    "name": "uniswap_tokens",
    "subgraphId": "...",
    "type": "...",
    "isDataScience": false
  }
}

Schedule Frequencies:

on_demand (default) - Report runs once immediately upon creation. Perfect for one-time analysis or API-only reports.
daily - Report runs automatically every day
weekly - Report runs automatically every week
monthly - Report runs automatically every month

API-Only Reports: You can create reports without email recipients by omitting the recipients field and setting:

emailEnabled: false - Disable email delivery
deliveryApiRetention: true - Enable API access to report data
refId: "your-reference" - Use your own reference ID to easily find the report later

// Example: Create an API-only report
const apiOnlyReport = await axios.post('https://api.pond3r.xyz/v1/api/reports', {
  prompt: 'Analyze DeFi trends',
  datasetId: 'uuid-of-dataset',
  scheduleFrequency: 'on_demand',
  emailEnabled: false,
  deliveryApiRetention: true,
  refId: 'defi-analysis-2024'
}, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

List User Reports

GET /v1/api/reports - List all reports created by the authenticated user

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports?page=1&limit=10', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "data": [
    {
      "id": "uuid",
      "prompt": "...",
      "datasetId": "uuid",
      "scheduleFrequency": "daily",
      "deliverySubject": "Daily Token Report",
      "deliveryApiRetention": true,
      "active": true,
      "status": "COMPLETED",
      "workflowType": "SCHEDULED",
      "createdAt": "2024-03-24T09:00:00Z",
      "recipients": [...]
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 10
}

Get Report Status

GET /v1/api/reports/{reportId}/status - Get current processing status of a report

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/uuid/status', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "status": "COMPLETED", // or "PENDING", "GENERATING", "FAILED"
  "reportId": "uuid",
  "lastExecutedAt": "2024-03-24T09:00:00Z"
}

List Reports by Reference ID

GET /v1/api/reports/by-ref/{refId} - List all reports with a specific reference ID Multiple reports can share the same refId. This endpoint returns all matching reports with pagination support.

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/by-ref/user-123?page=1&limit=10', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "data": [
    {
      "id": "uuid-1",
      "prompt": "Weekly analysis",
      "datasetId": "uuid-of-dataset",
      "scheduleFrequency": "weekly",
      "refId": "user-123",
      "deliveryApiRetention": true,
      "active": true,
      "status": "COMPLETED",
      "createdAt": "2024-03-24T09:00:00Z",
      "recipients": [...],
      "dataset": {...}
    },
    {
      "id": "uuid-2",
      "prompt": "Daily opportunities",
      "datasetId": "uuid-of-dataset",
      "scheduleFrequency": "daily",
      "refId": "user-123",
      "deliveryApiRetention": true,
      "active": true,
      "status": "COMPLETED",
      "createdAt": "2024-03-23T09:00:00Z",
      "recipients": [...],
      "dataset": {...}
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 10
}

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 10)

Access Control: Only returns reports you created. Returns empty array if no reports found.

Delete Report

DELETE /v1/api/reports/{reportId} - Delete a scheduled report

const response = await axios.delete('https://api.pond3r.xyz/v1/api/reports/uuid', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "message": "Report successfully deleted"
}

Access Control:

Only the report owner can delete a report
Returns 403 Forbidden if you don’t own the report
Returns 404 Not Found if the report doesn’t exist

Get Dataset Catalog

GET /v1/api/reports/dataset-catalog - List available datasets for creating reports

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/dataset-catalog', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response: Dataset catalog from the reports service
{
  "datasets": [
    {
      "id": "uuid",
      "name": "uniswap_tokens",
      "description": "Uniswap token data and metrics",
      "availableFields": [...]
    }
  ]
}

Discover Reports

GET /v1/api/reports/discover - List available API-enabled reports (owned by you or public)

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/discover?page=1&limit=10', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "reports": [
    {
      "id": "uuid",
      "subject": "New Token Opportunities",
      "frequency": "daily",
      "datasetName": "uniswap_tokens"
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 10
}

List Report Executions

GET /v1/api/reports/{reportId}/executions - Get execution history for a report

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/uuid/executions?page=1&limit=10&contentType=both', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "executions": [
    {
      "id": "execution-uuid",
      "createdAt": "2024-03-24T09:00:00Z",
      "status": "COMPLETED",
      "hasMarkdown": true,
      "hasJson": true
    }
  ],
  "total": 30,
  "page": 1,
  "limit": 10
}

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 10)
contentType - Filter by content type: markdown, json, or both (default: both)

Get Markdown Content

GET /v1/api/reports/executions/{executionId}/markdown - Retrieve markdown report content

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/executions/uuid/markdown', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "executionId": "uuid",
  "reportId": "report-uuid",
  "createdAt": "2024-03-24T09:00:00Z",
  "subject": "New Token Opportunities",
  "markdownContent": "# Daily Token Analysis Report\n\n## Executive Summary...",
  "metadata": {
    "generatedAt": "2024-03-24T09:00:00Z",
    "datasetName": "uniswap_tokens"
  }
}

Get JSON Content

GET /v1/api/reports/executions/{executionId}/json - Retrieve structured JSON report content

const response = await axios.get('https://api.pond3r.xyz/v1/api/reports/executions/uuid/json', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// Response:
{
  "executionId": "uuid",
  "reportId": "report-uuid",
  "createdAt": "2024-03-24T09:00:00Z",
  "subject": "New Token Opportunities",
  "jsonContent": {
    "executiveSummary": {
      "keyFindings": "3 new tokens identified with 50%+ liquidity growth",
      "topOpportunity": "TOKEN_ABC showing 85% volume increase"
    },
    "opportunities": [
      {
        "token": "TOKEN_ABC",
        "riskScore": 0.3,
        "opportunitySize": "High",
        "details": "Rising liquidity with institutional backing",
        "marketCap": 450000,
        "volumeChange": 0.85
      }
    ]
  },
  "metadata": {
    "generatedAt": "2024-03-24T09:00:00Z",
    "datasetName": "uniswap_tokens"
  }
}

Workflow

The typical workflow for using the Reports API:

Get Datasets - Use /dataset-catalog to see available data sources
Create Report - Submit a new report with your prompt and dataset
Check Status - Monitor report generation via /reports/{reportId}/status
Discover Reports - Use /discover to find API-enabled reports
Access Executions - List historical runs with /reports/{reportId}/executions
Retrieve Content - Get report data in markdown or JSON format

Example: Create and Access a Report

// 1. Get available datasets
const datasets = await axios.get('https://api.pond3r.xyz/v1/api/reports/dataset-catalog', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

const uniswapDatasetId = datasets.data.datasets.find(d => d.name === 'uniswap_tokens').id;

// 2. Create a new on-demand API-only report
const report = await axios.post('https://api.pond3r.xyz/v1/api/reports', {
  prompt: 'Analyze tokens with rising liquidity',
  datasetId: uniswapDatasetId,
  scheduleFrequency: 'on_demand',  // Runs once immediately
  emailEnabled: false,              // No email notifications
  deliveryApiRetention: true,       // Enable API access
  refId: 'liquidity-analysis-001'   // Custom reference ID
}, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

const reportId = report.data.id;

// 3. Check status
const status = await axios.get(`https://api.pond3r.xyz/v1/api/reports/${reportId}/status`, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

// 4. List reports by reference ID (alternative to using reportId)
const reportsByRef = await axios.get('https://api.pond3r.xyz/v1/api/reports/by-ref/liquidity-analysis-001', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

const firstReport = reportsByRef.data.data[0]; // Get the first matching report

// 5. List executions (once report has run)
const executions = await axios.get(`https://api.pond3r.xyz/v1/api/reports/${reportId}/executions`, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

const latestExecutionId = executions.data.executions[0].id;

// 6. Get the report content in JSON format
const jsonContent = await axios.get(`https://api.pond3r.xyz/v1/api/reports/executions/${latestExecutionId}/json`, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

console.log(jsonContent.data.jsonContent);

// 7. Delete the report when done
await axios.delete(`https://api.pond3r.xyz/v1/api/reports/${reportId}`, {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

Authentication

All endpoints require API key authentication via the x-api-key header:

headers: {
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

Response Status Codes

200 - Success
201 - Created (for new reports)
400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid or missing API key)
403 - Forbidden (insufficient permissions)
404 - Not Found (report or execution doesn’t exist)
429 - Rate Limited
500 - Internal Server Error

Rate Limits

Report creation: 10 requests per hour
Data access: 1000 requests per hour

Access Control

Reports have two access levels:

Private (default): Only accessible to the creator via their API key
Public (isPublic: true): Accessible to all authenticated users via the discover endpoint

To enable API access to execution data, set deliveryApiRetention: true when creating the report.

Need help getting started? Join our Discord community or reach out via Twitter.

API Documentation

Endpoint Examples

Overview

Endpoints

Create Report

List User Reports

Get Report Status

List Reports by Reference ID

Delete Report

Get Dataset Catalog

Discover Reports

List Report Executions

Get Markdown Content

Get JSON Content

Workflow

Example: Create and Access a Report

Authentication

Response Status Codes

Rate Limits

Access Control

API Documentation

Endpoint Examples

Documentation Index

​Overview

​Endpoints

​Create Report

​List User Reports

​Get Report Status

​List Reports by Reference ID

​Delete Report

​Get Dataset Catalog

​Discover Reports

​List Report Executions

​Get Markdown Content

​Get JSON Content

​Workflow

​Example: Create and Access a Report

​Authentication

​Response Status Codes

​Rate Limits

​Access Control

Overview

Endpoints

Create Report

List User Reports

Get Report Status

List Reports by Reference ID

Delete Report

Get Dataset Catalog

Discover Reports

List Report Executions

Get Markdown Content

Get JSON Content

Workflow

Example: Create and Access a Report

Authentication

Response Status Codes

Rate Limits

Access Control