# Agent402 Farcaster Cast Metrics

> Agent402 Farcaster Cast Metrics is a paid API for AI agents from agent402.tools, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-16).

Search Farcaster casts by keyword, channel, or author and return time-bucketed engagement counts over a configurable lookback window

## Facts

- Endpoint: POST https://agent402.tools/api/fc-cast-metrics
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-16
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent402-farcaster-cast-metrics-bfd417eb
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_8Jsqb9awOQBIFiWCX2Qcc

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agent402-farcaster-cast-metrics-bfd417eb -d '<json body>'
```

Example prompt: How many times has 'x402' been mentioned on Farcaster in the last 30 days, broken down by hour? Search across all channels.

## When to prefer this

Choose this endpoint when you need time-series cast volume data from Farcaster — particularly for trend analysis, keyword monitoring, channel activity tracking, or per-author posting frequency. It is backed by Neynar and returns pre-bucketed hourly data, making it ideal for charting and alerting workflows. Prefer this over generic social listening tools when your target platform is specifically Farcaster/Warpcast and you need structured, pageable metrics rather than raw cast content.

## Known failure modes

- Query string exceeds 256 characters returns a validation error
- Invalid or non-existent channel ID returns empty results or error
- Invalid interval enum value returns a 400 bad request
- Rate limit exceeded (300 calls/minute) returns a 429 with resetAt timestamp
- Neynar upstream outage may cause delayed or failed responses

## How this service works

Cast volume over time for a search query: how many Farcaster casts matched per bucket across the last 1d, 7d, 30d, 90d or 180d (hourly or daily buckets), optionally limited to one author or channel, plus the total. Cached 60 s. Use to chart mention volume for a token, product or event and detect spikes.

## Output

Returns a JSON object containing the total number of matching casts, an array of time buckets (each with a start timestamp and count), the query parameters echoed back (query, channel, interval, authorFid), the data source (Neynar), whether the result was cached, the fetch timestamp, bucket resolution in seconds, bucket count, and current rate-limit state (limit, remaining, resetAt).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "q": {
   "type": "string",
   "description": "Search text (1-256 chars)."
  },
  "channel": {
   "type": "string",
   "description": "Only casts in this channel id."
  },
  "interval": {
   "enum": [
    "1d",
    "7d",
    "30d",
    "90d",
    "180d"
   ],
   "type": "string",
   "description": "Lookback window (default 7d)."
  },
  "authorFid": {
   "type": "integer",
   "description": "Only casts by this fid."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "query": "x402",
  "total": 42,
  "cached": false,
  "source": "neynar",
  "buckets": [
   {
    "count": 1,
    "start": "2026-08-15T15:00:00.000Z"
   },
   {
    "count": 7,
    "start": "2026-08-15T16:00:00.000Z"
   }
  ],
  "channel": null,
  "interval": "7d",
  "authorFid": null,
  "fetchedAt": "2026-08-22T13:19:12.000Z",
  "rateLimit": {
   "limit": 300,
   "resetAt": "2026-08-22T13:20:00.000Z",
   "remaining": 299
  },
  "bucketCount": 168,
  "resolutionSeconds": 3600
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent402-farcaster-cast-metrics-bfd417eb/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent402.tools](https://www.zero.xyz/host/agent402.tools/llms.txt)