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

# Alerts

> Alert system endpoints

## Alert Inbox

<ParamField path="GET" method="/api/alerts/inbox">
  Get the alert inbox with filtering and pagination.
</ParamField>

### Query Parameters

<ParamField query="limit" type="number" default="50">
  Results per page (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset
</ParamField>

<ParamField query="type" type="string">
  Filter by alert type: `injury`, `arbitrage`, `political`, `finance`, `crowding`, `conflict`, `rumor`
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "alert-uuid",
        "type": "injury",
        "subtype": "nfl",
        "headline": "Patrick Mahomes listed as questionable",
        "sentAt": "2025-01-28T10:00:00Z",
        "entity": {
          "slug": "patrick-mahomes",
          "displayName": "Patrick Mahomes"
        }
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 50,
      "offset": 0
    },
    "unreadCount": 12
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/alerts/inbox?type=injury&limit=20"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/alerts/inbox?type=injury&limit=20'
  );
  const { data } = await response.json();
  console.log(`Unread: ${data.unreadCount}`);
  ```
</CodeGroup>

***

## Get Alert

<ParamField path="GET" method="/api/alerts/:id">
  Get full alert details including entity context, related markets, and cross-venue data.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Alert ID
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "alert-uuid",
    "type": "injury",
    "subtype": "nfl",
    "headline": "Patrick Mahomes listed as questionable",
    "sentAt": "2025-01-28T10:00:00Z",
    "entity": {
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person",
      "attributes": { ... }
    },
    "relatedMarkets": [
      {
        "title": "Chiefs to win Super Bowl",
        "venue": "polymarket",
        "price": 0.35
      }
    ],
    "crossVenueData": { ... },
    "attribution": { ... },
    "engagement": {
      "read": true,
      "dismissed": false,
      "acted": false
    }
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/alerts/alert-uuid"
  ```
</CodeGroup>

***

## Alert Outcome

<ParamField path="GET" method="/api/alerts/:id/outcome">
  Get outcome tracking data for an alert — how the market moved after the alert was sent.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Alert ID
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "alert-uuid",
    "type": "injury",
    "subtype": "nfl",
    "asset": "patrick-mahomes",
    "headline": "Mahomes listed as questionable",
    "sentAt": "2025-01-28T10:00:00Z",
    "hoursSinceAlert": 24,
    "outcomeTracked": true,
    "outcomeTrackedAt": "2025-01-29T10:00:00Z",
    "priceAtAlert": 0.35,
    "priceAt1h": 0.32,
    "priceAt4h": 0.30,
    "priceAt24h": 0.28,
    "priceAtResolution": 0.25,
    "priceChange1hBps": -300,
    "priceChange4hBps": -500,
    "priceChange24hBps": -700,
    "expectedDirection": "down",
    "actualDirection1h": "down",
    "actualDirection24h": "down",
    "directionCorrect": true,
    "outcomeScore": 0.85,
    "outcomeNotes": "Market moved as expected after injury downgrade"
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/alerts/alert-uuid/outcome"
  ```
</CodeGroup>

***

## Outcome Stats

<ParamField path="GET" method="/api/alerts/outcomes/stats">
  Get aggregate alert performance statistics.
</ParamField>

### Query Parameters

<ParamField query="days" type="number" default="30">
  Lookback period in days
</ParamField>

<ParamField query="type" type="string">
  Filter by alert type
</ParamField>

<ParamField query="entity" type="string">
  Filter by entity slug
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "totalAlerts": 500,
    "trackedAlerts": 450,
    "directionAccuracy": 0.72,
    "averageScore": 0.65,
    "byType": {
      "injury": { "count": 200, "accuracy": 0.78 },
      "arbitrage": { "count": 100, "accuracy": 0.85 },
      "political": { "count": 80, "accuracy": 0.60 }
    }
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/alerts/outcomes/stats?days=30&type=injury"
  ```
</CodeGroup>

***

## Top Outcomes

<ParamField path="GET" method="/api/alerts/outcomes/top">
  Get top-performing alerts by outcome score.
</ParamField>

### Query Parameters

<ParamField query="limit" type="number" default="10">
  Maximum results (max: 50)
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "alert-uuid",
      "type": "injury",
      "headline": "Mahomes listed as out",
      "outcomeScore": 0.95,
      "priceChange24hBps": -1200,
      "directionCorrect": true
    }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/alerts/outcomes/top?limit=10"
  ```
</CodeGroup>