---
title: Transactions
description: View and search your transaction history
---

# Transactions

The Transactions API returns your transaction history with filtering, pagination, and statistics.

## Endpoint

```http
GET /api/transactions
```

## Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | `1` | Page number |
| `limit` | integer | `20` | Items per page (max: 100) |
| `status` | string | - | Filter by status: `success`, `failed`, `pending` |
| `search` | string | - | Search by endpoint URL |
| `network` | string | - | Filter by network |
| `startDate` | string | - | Filter from date (ISO 8601) |
| `endDate` | string | - | Filter to date (ISO 8601) |

## Response

```json
{
  "transactions": [
    {
      "id": "tx_abc123",
      "amount_usd": 0.25,
      "network": "base-sepolia",
      "endpoint": "https://api.example.com/generate",
      "timestamp": "2025-01-09T12:00:00Z",
      "status": "success",
      "scheme": "exact",
      "tx_hash": "0x1234..."
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 100,
    "limit": 20
  },
  "stats": {
    "totalSpent": 25.50,
    "successRate": 95.0,
    "transactionCount": 100
  }
}
```

### Transaction Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique transaction ID |
| `amount_usd` | number | Amount in USD |
| `network` | string | Blockchain network |
| `endpoint` | string | API endpoint accessed |
| `timestamp` | string | ISO 8601 timestamp |
| `status` | string | `success`, `failed`, or `pending` |
| `scheme` | string | Authorization scheme used |
| `tx_hash` | string | Blockchain transaction hash |

### Pagination Object

| Field | Type | Description |
|-------|------|-------------|
| `currentPage` | number | Current page number |
| `totalPages` | number | Total number of pages |
| `totalCount` | number | Total transaction count |
| `limit` | number | Items per page |

### Stats Object

| Field | Type | Description |
|-------|------|-------------|
| `totalSpent` | number | Total USD spent |
| `successRate` | number | Percentage of successful transactions |
| `transactionCount` | number | Total number of transactions |

## Examples

### Get Recent Transactions

```bash
curl https://api.agnic.ai/api/transactions \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Filter by Status

```bash
curl "https://api.agnic.ai/api/transactions?status=success" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Search by Endpoint

```bash
curl "https://api.agnic.ai/api/transactions?search=openai" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Paginate Results

```bash
curl "https://api.agnic.ai/api/transactions?page=2&limit=50" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Filter by Date Range

```bash
curl "https://api.agnic.ai/api/transactions?startDate=2025-01-01&endDate=2025-01-31" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Python Example

```python
import requests

def get_transactions(page=1, limit=20, status=None):
    params = {"page": page, "limit": limit}
    if status:
        params["status"] = status

    response = requests.get(
        "https://api.agnic.ai/api/transactions",
        headers={"X-Agnic-Token": "agnic_tok_YOUR_TOKEN"},
        params=params
    )

    return response.json()

# Get all successful transactions
data = get_transactions(status="success")

print(f"Total spent: ${data['stats']['totalSpent']}")
print(f"Success rate: {data['stats']['successRate']}%")

for tx in data["transactions"]:
    print(f"{tx['timestamp']}: ${tx['amount_usd']} to {tx['endpoint']}")
```

### JavaScript Example

```javascript
async function getTransactions(options = {}) {
  const params = new URLSearchParams({
    page: options.page || 1,
    limit: options.limit || 20,
    ...(options.status && { status: options.status }),
    ...(options.search && { search: options.search })
  });

  const response = await fetch(
    `https://api.agnic.ai/api/transactions?${params}`,
    {
      headers: {
        'X-Agnic-Token': 'agnic_tok_YOUR_TOKEN'
      }
    }
  );

  return response.json();
}

// Get recent transactions
const data = await getTransactions({ limit: 10 });

console.log(`Total spent: $${data.stats.totalSpent}`);
data.transactions.forEach(tx => {
  console.log(`${tx.timestamp}: $${tx.amount_usd}`);
});
```

## Monitoring Spending

### Daily Spending Report

```python
from datetime import datetime, timedelta
import requests

def get_daily_spending():
    today = datetime.now().date()
    yesterday = today - timedelta(days=1)

    response = requests.get(
        "https://api.agnic.ai/api/transactions",
        headers={"X-Agnic-Token": "agnic_tok_YOUR_TOKEN"},
        params={
            "startDate": str(yesterday),
            "endDate": str(today),
            "limit": 100
        }
    )

    data = response.json()
    return data["stats"]["totalSpent"]

print(f"Spent yesterday: ${get_daily_spending()}")
```

### Top Endpoints by Spend

```python
from collections import defaultdict

def get_top_endpoints():
    response = requests.get(
        "https://api.agnic.ai/api/transactions",
        headers={"X-Agnic-Token": "agnic_tok_YOUR_TOKEN"},
        params={"limit": 100, "status": "success"}
    )

    spending = defaultdict(float)
    for tx in response.json()["transactions"]:
        spending[tx["endpoint"]] += tx["amount_usd"]

    return sorted(spending.items(), key=lambda x: x[1], reverse=True)

for endpoint, amount in get_top_endpoints()[:5]:
    print(f"${amount:.2f} - {endpoint}")
```

<Cards>
  <Card title="Balance" href="/docs/agnicpay-features/balance" />
  <Card title="API Tokens" href="/docs/authentication/api-tokens" />
</Cards>