> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pond3r.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports API

> Manage and access automated crypto intelligence reports

## 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

```javascript theme={null}
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

```javascript theme={null}
// 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

```javascript theme={null}
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

```javascript theme={null}
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.

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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)

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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:

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

### Example: Create and Access a Report

```javascript theme={null}
// 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:

```javascript theme={null}
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.

<Note>
  Need help getting started? Join our [Discord community](https://discord.gg/yK9eg5Sr7e) or reach out via [Twitter](https://twitter.com/pond3r).
</Note>