AIDRANDevelopers

Reference

API Reference

Programmatic access to AIDRAN's discourse intelligence. All endpoints return JSON, use API key authentication, and are versioned under /api/v1.

Quick Start

Get your API key and start querying discourse data in minutes. The free tier includes 100 requests per day — enough to evaluate the API and build a prototype.

Get your API keyOpen Playground
Base URL
https://aidran.ai/api/v1

Authentication

All endpoints (except /status) require an API key via either header:

curl
curl -H "x-api-key: YOUR_KEY" \
  https://aidran.ai/api/v1/topics
curl
curl -H "Authorization: Bearer YOUR_KEY" \
  https://aidran.ai/api/v1/topics

Generate API keys instantly from the Developer Portal. Keys are prefixed with aidr_ and shown once at creation -- store them securely.

Rate Limits

Rate limits are enforced per API key at two levels: requests per minute (RPM) and requests per day (RPD). Limits reset at the top of each minute and at midnight UTC respectively.

API rate limit tiers
TierRPMRPDKeysPrice
Free51001$0
Research605,00010$199/mo
EnterpriseCustomCustomCustomContact us

When rate-limited, the API returns 429 with a Retry-After header. The response body includes an upgrade URL for tier upgrades.

Pagination

List endpoints return paginated results using limit and offset parameters. The response includes a pagination object:

json
{
  "pagination": {
    "total": 2341,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

To fetch the next page, increment offset by limit. Maximum limit varies by endpoint (50–200).

Errors

Errors return a JSON object with an error field.

API error codes and meanings
StatusMeaningExample
400Bad request"q parameter is required"
401Invalid or missing API key"API key required"
404Resource not found"Topic not found"
429Rate limit exceeded (RPM or RPD)"Daily request limit reached"
500Internal server error"Search failed"
503API not configured"API access not configured"

Narratives

AIDRAN's editorial output — the lead stories, beat narratives, dispatches, and entity profiles that the system generates from raw discourse. These are the published artifacts that appear on the front page and beat pages, each one synthesized from dozens or hundreds of source records.

GET/api/v1/narrativesList narratives

Returns a paginated feed of all published narratives across every content type AIDRAN produces. Filter by narrative type, editorial beat, date window, or featured status to surface the stories that matter most — whether you are building a dashboard, populating a feed, or auditing editorial output over time.

Note: Results are ordered by generatedAt descending (newest first). The content field returns full text; use limit to control payload size.

Parameters

Parameters for List narratives
ParameterTypeRequiredDescription
typestringoptionalNarrative type: "lead_story", "beat_narrative", "dispatch", or "entity_narrative".
lead_storybeat_narrativedispatchentity_narrative
topicstringoptionalFilter by topic name.
featuredbooleanoptionalOnly return editorially featured narratives.
sinceISO 8601optionalNarratives generated after this date.
untilISO 8601optionalNarratives generated before this date.
limitintegeroptionalResults per page.Default: 20, max 50
offsetintegeroptionalPagination offset.Default: 0

Response Codes

Response codes for List narratives
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/narratives?type=lead_story&limit=5"
json
{
  "data": [
    {
      "slug": "open-source-ai-safety-debate-intensifies",
      "type": "lead_story",
      "headline": "Open-Source AI Safety Debate Intensifies...",
      "content": "The conversation around open-source AI safety...",
      "topic": "open-source-ai",
      "topicDisplayName": "Open-Source AI",
      "category": "development",
      "signalSeverity": "high",
      "featured": true,
      "generatedAt": "2026-03-26T14:30:00.000Z",
      "version": 3,
      "entityName": null
    }
  ],
  "pagination": {
    "total": 847,
    "limit": 5,
    "offset": 0,
    "hasMore": true
  }
}
Open in Playground →
GET/api/v1/narratives/:slugGet narrative

Retrieves the complete text of a single narrative along with its full provenance chain — the source discourse IDs it was synthesized from, inline cross-references to entities and related beats, and the version history showing how the story evolved. Use this when you need to display a full story or trace its editorial lineage back to raw discourse.

Note: The sourceDiscourseIds array provides full provenance tracing. The versions array is ordered newest-first.

Response Codes

Response codes for Get narrative
StatusMeaning
200Success
401Missing or invalid API key
404Resource not found
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/narratives/open-source-ai-safety-debate-intensifies"
json
{
  "slug": "open-source-ai-safety-debate-intensifies",
  "type": "lead_story",
  "headline": "Open-Source AI Safety Debate Intensifies...",
  "content": "The conversation around open-source AI safety...",
  "topic": "open-source-ai",
  "topicDisplayName": "Open-Source AI",
  "category": "development",
  "signalSeverity": "high",
  "triggerSignal": { "type": "volume_spike", "severity": "high" },
  "metadata": { "summary": "..." },
  "featured": true,
  "generatedAt": "2026-03-26T14:30:00.000Z",
  "version": 3,
  "entityName": null,
  "sourceDiscourseIds": [14823, 14856, 14901],
  "references": [
    { "refType": "entity", "refSlug": "meta", "displayText": "Meta" },
    { "refType": "beat", "refSlug": "ai-safety", "displayText": "AI Safety" }
  ],
  "versions": [
    { "slug": "open-source-ai-safety-v3", "version": 3, "generatedAt": "..." },
    { "slug": "open-source-ai-safety-v2", "version": 2, "generatedAt": "..." }
  ]
}
Open in Playground →

Topics

The editorial beats that structure AIDRAN's coverage — thematic areas like "AI Safety", "LLM Capabilities", or "AI Regulation". Each topic defines a lens through which the system watches discourse, complete with curated keywords, tracked subreddits, and category assignments.

GET/api/v1/topicsList topics

Returns every editorial beat AIDRAN is currently tracking, along with its display name, category, curated keyword list, and the subreddits wired into its ingestion pipeline. Use this to understand the full scope of AIDRAN's coverage or to build topic selectors in your own application.

Parameters

Parameters for List topics
ParameterTypeRequiredDescription
activebooleanoptionalFilter by active status.Default: true

Response Codes

Response codes for List topics
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/topics"
json
{
  "topics": [
    {
      "name": "ai-safety",
      "displayName": "AI Safety",
      "description": "Alignment research, interpretability, and safety...",
      "category": "governance",
      "keywords": ["alignment", "interpretability", "safety"],
      "subreddits": ["aisafety", "alignment_research"],
      "active": true,
      "createdAt": "2025-12-01T00:00:00.000Z"
    }
  ],
  "count": 23
}
Open in Playground →
GET/api/v1/topics/:nameGet topic detail

A comprehensive portrait of a single editorial beat. Returns the current beat narrative, recent intelligence signals, a 30-day sentiment trajectory, the most-mentioned entities, volume broken out by source platform, and active narrative clusters. This is the richest single-call view of any topic in the API — ideal for building beat pages or research dashboards.

Note: This is the richest single-call view of any topic. The snapshots array covers the last 30 days by default.

Response Codes

Response codes for Get topic detail
StatusMeaning
200Success
401Missing or invalid API key
404Resource not found
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/topics/ai-safety"
json
{
  "name": "ai-safety",
  "displayName": "AI Safety",
  "description": "Alignment research, interpretability, and safety...",
  "category": "governance",
  "keywords": ["alignment", "interpretability", "safety"],
  "active": true,
  "currentNarrative": {
    "slug": "ai-safety-narrative-v12",
    "headline": "Safety Benchmarks Under Scrutiny",
    "content": "This week's discourse around AI safety...",
    "signalSeverity": "medium",
    "generatedAt": "2026-03-25T08:00:00.000Z",
    "version": 12
  },
  "recentSignals": [
    { "type": "volume_spike", "severity": "high", "headline": "...", "detectedAt": "2026-03-24T16:00:00.000Z" }
  ],
  "snapshots": [
    {
      "date": "2026-03-25",
      "totalRecords": 142,
      "volumeBySource": { "reddit": 75, "bluesky": 40, "news": 18, "arxiv": 9 },
      "sentimentPositive": 52,
      "sentimentNeutral": 68,
      "sentimentNegative": 22,
      "avgSentimentScore": "0.34",
      "topEntities": [{ "name": "Anthropic", "mentions": 12, "type": "organization" }],
      "signalCount": 2
    }
  ],
  "clusters": [
    {
      "clusterLabel": 0,
      "recordCount": 34,
      "topTerms": ["alignment", "RLHF", "constitutional"],
      "summaryLabel": "Alignment training approaches",
      "createdAt": "2026-03-25T08:00:00.000Z"
    }
  ],
  "volumeBySource": [
    { "source": "reddit", "count": 89 },
    { "source": "bluesky", "count": 34 }
  ]
}
Open in Playground →

Discourse

The raw material that powers everything else — individual discourse records collected from Reddit, Bluesky, Hacker News, news outlets, arXiv, YouTube, and Twitter/X. Each record carries its original text, metadata, and AI-generated analysis including sentiment, themes, and extracted entities.

GET/api/v1/discourseQuery discourse records

Query the full corpus of ingested discourse records with filters for source platform, editorial beat, and time window. Each record includes the original text, publication metadata, and — when analysis has completed — AI-generated sentiment scores, thematic tags, and extracted entities. Use this for corpus-level research, custom aggregations, or building your own analysis on top of AIDRAN's raw data.

Note: The analysis field may be null for recently ingested records that have not yet been processed by the analysis pipeline. Records are ordered by capturedAt descending.

Parameters

Parameters for Query discourse records
ParameterTypeRequiredDescription
sourcestringoptionalPlatform filter: "reddit", "bluesky", "news", "hackernews", "arxiv", "youtube", "twitter".
redditblueskynewshackernewsarxivyoutubetwitter
topicstringoptionalFilter by topic name.
sinceISO 8601optionalRecords captured after this date.
untilISO 8601optionalRecords captured before this date.
limitintegeroptionalResults per page.Default: 50, max 100
offsetintegeroptionalPagination offset.Default: 0

Response Codes

Response codes for Query discourse records
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/discourse?source=reddit&topic=ai-safety&limit=10"
json
{
  "data": [
    {
      "id": "14823",
      "source": "reddit",
      "contentType": "post",
      "sourceId": "t3_abc123",
      "title": "New interpretability paper from Anthropic",
      "contentText": "Just read through the latest...",
      "url": "https://reddit.com/r/aisafety/...",
      "author": "researcher_42",
      "publishedAt": "2026-03-25T19:30:00.000Z",
      "capturedAt": "2026-03-25T20:00:00.000Z",
      "topic": "ai-safety",
      "subreddit": "aisafety",
      "language": "en",
      "analysis": {
        "sentiment": { "label": "positive", "score": 0.72 },
        "themes": ["interpretability", "transparency"],
        "entities": [{ "text": "Anthropic", "type": "organization" }]
      }
    }
  ],
  "pagination": { "total": 2341, "limit": 10, "offset": 0, "hasMore": true }
}
Open in Playground →

Search

Semantic search across the entire discourse corpus, powered by Voyage AI embeddings (voyage-4-lite, 512-dim) and pgvector nearest-neighbor lookup. Find records by meaning rather than exact keywords — ask a conceptual question and get the most relevant discourse back, ranked by cosine similarity.

GET/api/v1/searchSemantic search

Submit a natural-language query and receive the most semantically relevant discourse records, ranked by vector similarity. The query is embedded in real time using Voyage AI, then matched against the full corpus via pgvector. Results include relevance scores, source metadata, and timing diagnostics. Use this when keyword search falls short — for exploratory research, concept mapping, or finding related conversations across platforms.

Note: Results are ranked by cosine similarity. Minimum 3-character query required. The embeddingMs and searchMs fields are useful for performance monitoring.

Parameters

Parameters for Semantic search
ParameterTypeRequiredDescription
qstringrequiredSearch query. Max 500 characters.
sourcestringoptionalFilter by platform.
redditblueskynewshackernewsarxivyoutubetwitter
topicstringoptionalFilter by topic name.
daysintegeroptionalLimit to records from the last N days.
limitintegeroptionalMax results.Default: 20, max 50

Response Codes

Response codes for Semantic search
StatusMeaning
200Success
400Missing required parameter
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/search?q=constitutional+AI+training&days=30"
json
{
  "results": [
    {
      "id": "14901",
      "resultType": "discourse",
      "source": "arxiv",
      "contentType": "paper",
      "title": "Constitutional AI approaches compared",
      "excerpt": "There are several approaches to...",
      "url": "https://arxiv.org/abs/2603.12345",
      "href": "/search?q=constitutional+AI+training",
      "author": "research_team",
      "topic": "ai-safety",
      "topicDisplayName": "AI Safety",
      "category": "governance",
      "relevance": 0.891,
      "publishedAt": "2026-03-22T00:00:00.000Z",
      "subreddit": null,
      "sentimentLabel": "neutral"
    }
  ],
  "query": "constitutional AI training",
  "totalMatched": 23,
  "hasMore": true,
  "embeddingMs": 120,
  "searchMs": 45
}
Open in Playground →

Signals

Intelligence signals detected by AIDRAN's analysis pipeline — the early-warning system that flags noteworthy shifts in AI discourse. Signals include volume spikes, sentiment reversals, emerging narrative threads, and cross-platform divergences, each graded by severity and linked to the beat where they were detected.

GET/api/v1/signalsList signals

Returns a paginated feed of intelligence signals detected across all editorial beats. Filter by topic, severity level, or detection date to zero in on the moments that matter — a sudden spike in safety discourse, a sentiment reversal around a product launch, or an emerging narrative that has not yet been covered. Each signal includes its type, severity, a human-readable headline, and structured detail.

Note: Signals are ordered by detectedAt descending. The detail field structure varies by signal type (e.g. volume_spike includes baseline/current/multiplier, sentiment_shift includes before/after scores).

Parameters

Parameters for List signals
ParameterTypeRequiredDescription
topicstringoptionalFilter by topic name.
severitystringoptionalFilter by severity: "high", "medium", "low".
highmediumlow
sinceISO 8601optionalSignals detected after this date.
limitintegeroptionalResults per page.Default: 50, max 100
offsetintegeroptionalPagination offset.Default: 0

Response Codes

Response codes for List signals
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/signals?severity=high&since=2026-03-20"
json
{
  "data": [
    {
      "id": 312,
      "type": "volume_spike",
      "topic": "llm-capabilities",
      "severity": "high",
      "headline": "3.2x volume spike in LLM benchmark discussions",
      "detail": { "baseline": 45, "current": 144, "multiplier": 3.2 },
      "detectedAt": "2026-03-24T16:00:00.000Z",
      "acknowledged": false,
      "narrativeId": null
    }
  ],
  "pagination": { "total": 89, "limit": 50, "offset": 0, "hasMore": true }
}
Open in Playground →

Entities

The people, organizations, technologies, and products that shape AI discourse — extracted from every analyzed record and aggregated into mention-ranked profiles. Use these endpoints to track who and what the community is talking about, and how that attention changes over time.

GET/api/v1/entitiesAggregate entities

Returns the most-discussed entities across AIDRAN's discourse corpus, ranked by mention count and filterable by topic and time window. Each entry includes the entity name, mention total, and type classifications. Use this to build leaderboards, spot rising players in a beat, or compare mindshare across organizations and technologies.

Parameters

Parameters for Aggregate entities
ParameterTypeRequiredDescription
topicstringoptionalFilter by topic name. Defaults to all.
sinceISO 8601optionalAggregate from this date.Default: 7 days ago
limitintegeroptionalMax entities returned.Default: 50, max 200

Response Codes

Response codes for Aggregate entities
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/entities?topic=llm-capabilities&limit=10"
json
{
  "data": [
    { "name": "OpenAI", "mentions": 234, "types": ["organization"] },
    { "name": "GPT-5", "mentions": 189, "types": ["technology"] },
    { "name": "Sam Altman", "mentions": 156, "types": ["person"] }
  ],
  "count": 10,
  "params": { "topic": "llm-capabilities", "since": "2026-03-19" }
}
Open in Playground →
GET/api/v1/entities/:nameGet entity profile

A full dossier on a single entity — its type classification, lifetime mention count, first and last appearance in the corpus, associated editorial beats, an AI-generated entity narrative summarizing its role in discourse, and a 30-day mention trend. Use this to power entity profile pages or to understand how a company, person, or technology has been discussed over time.

Note: Entity names are case-sensitive and must be URL-encoded. The mentionTrend array covers the last 30 days, ordered newest-first.

Response Codes

Response codes for Get entity profile
StatusMeaning
200Success
401Missing or invalid API key
404Resource not found
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/entities/OpenAI"
json
{
  "name": "OpenAI",
  "type": "organization",
  "types": ["organization"],
  "totalMentions": 4521,
  "firstSeen": "2025-12-15T00:00:00.000Z",
  "lastSeen": "2026-03-26T12:00:00.000Z",
  "beats": ["llm-capabilities", "ai-safety", "ai-business"],
  "narrative": {
    "headline": "OpenAI remains the most discussed...",
    "content": "OpenAI continues to dominate AI discourse...",
    "slug": "entity-openai-v8",
    "generatedAt": "2026-03-25T08:00:00.000Z"
  },
  "mentionTrend": [
    { "day": "2026-03-25", "mentions": 89 },
    { "day": "2026-03-24", "mentions": 72 }
  ]
}
Open in Playground →

Analytics

Longitudinal analysis and cross-topic comparison endpoints that reveal the deeper patterns in AI discourse. Daily snapshots, volume trends, side-by-side topic comparisons, and meta-observations that surface convergences, anomalies, and milestones the individual-beat view would miss.

GET/api/v1/snapshotsDaily snapshots

Pre-computed daily rollups that distill each topic's activity into a single row per day — total volume, volume broken out by source platform, sentiment distribution (positive/neutral/negative counts plus a weighted average), the day's top entities, and how many signals fired. Use snapshots to power time-series charts, historical comparisons, or any analysis that needs structured daily data without scanning the full corpus.

Note: Defaults to the last 30 days if from/to are omitted. Each row represents one calendar day in UTC. The avgSentimentScore is a string-encoded decimal for precision.

Parameters

Parameters for Daily snapshots
ParameterTypeRequiredDescription
topicstringrequiredTopic name. Required.
fromdateoptionalStart date (YYYY-MM-DD).
todateoptionalEnd date (YYYY-MM-DD).

Response Codes

Response codes for Daily snapshots
StatusMeaning
200Success
400Missing required parameter
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/snapshots?topic=ai-safety&from=2026-03-01"
json
{
  "topic": "ai-safety",
  "days": 26,
  "data": [
    {
      "date": "2026-03-01",
      "totalRecords": 87,
      "volumeBySource": { "reddit": 45, "bluesky": 22, "news": 12, "arxiv": 8 },
      "sentimentPositive": 31,
      "sentimentNeutral": 42,
      "sentimentNegative": 14,
      "avgSentimentScore": "0.34",
      "platformCount": 4,
      "topEntities": [
        { "name": "Anthropic", "mentions": 12, "type": "organization" }
      ],
      "signalCount": 2
    }
  ]
}
Open in Playground →
GET/api/v1/trendsVolume trends

A lightweight endpoint that returns daily discourse volume for a given topic — just date-count pairs, plus any external trend signals detected in that window. If you only need a volume sparkline or a quick activity overview, this is faster and simpler than /snapshots. For richer data including sentiment and entity breakdowns, use the snapshots endpoint instead.

Note: The volume array is ordered chronologically (oldest first). Use /snapshots instead if you need sentiment or entity data alongside volume.

Parameters

Parameters for Volume trends
ParameterTypeRequiredDescription
topicstringrequiredTopic name. Required.
daysintegeroptionalNumber of days to look back.Default: 30

Response Codes

Response codes for Volume trends
StatusMeaning
200Success
400Missing required parameter
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/trends?topic=ai-safety&days=14"
json
{
  "topic": "ai-safety",
  "days": 14,
  "volume": [
    { "day": "2026-03-12", "count": 67 },
    { "day": "2026-03-13", "count": 94 }
  ],
  "externalTrends": []
}
Open in Playground →
GET/api/v1/compareCompare topics

Places two to five editorial beats side by side, returning daily snapshot data for each so you can compare attention levels, sentiment trajectories, and entity overlap in a single call. Ideal for research that asks "how does discourse around AI safety track relative to AI regulation?" or for building multi-topic comparison views.

Note: Accepts 2-5 topics. Topics must be comma-separated. If fewer than 2 or more than 5 topics are provided, a 400 error is returned.

Parameters

Parameters for Compare topics
ParameterTypeRequiredDescription
topicsstringrequiredComma-separated topic names (2–5 required).
daysintegeroptionalNumber of days to compare.Default: 30, max 90

Response Codes

Response codes for Compare topics
StatusMeaning
200Success
400Missing required parameter
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/compare?topics=ai-safety,llm-capabilities&days=14"
json
{
  "topics": [
    { "name": "ai-safety", "displayName": "AI Safety", "category": "governance" },
    { "name": "llm-capabilities", "displayName": "LLM Capabilities", "category": "technology" }
  ],
  "days": 14,
  "comparison": {
    "ai-safety": [{ "date": "2026-03-12", "totalRecords": 67 }],
    "llm-capabilities": [{ "date": "2026-03-12", "totalRecords": 134 }]
  }
}
Open in Playground →
GET/api/v1/observationsMeta-observations

Surfaces the higher-order patterns that span multiple editorial beats — convergences where two topics begin sharing language or entities, divergences where sentiment splits across platforms, anomalies that break from historical norms, milestones like record volumes, and emerging trends not yet assigned to a beat. These are the observations that give AIDRAN its editorial edge: the ability to see the discourse landscape as a whole.

Note: The detail field structure varies by observation type. Convergence observations include the topics involved and shared entities; anomaly observations include the metric that deviated and by how much.

Parameters

Parameters for Meta-observations
ParameterTypeRequiredDescription
typestringoptionalFilter by type: "convergence", "divergence", "anomaly", "milestone", "trend".
convergencedivergenceanomalymilestonetrend
severitystringoptionalFilter by severity: "high", "medium", "low".
highmediumlow
sinceISO 8601optionalObservations after this date.
limitintegeroptionalResults per page.Default: 50, max 100
offsetintegeroptionalPagination offset.Default: 0

Response Codes

Response codes for Meta-observations
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/observations?type=convergence&severity=high"
json
{
  "data": [
    {
      "type": "convergence",
      "headline": "AI Safety and Open-Source AI converging on governance",
      "detail": { "topics": ["ai-safety", "open-source-ai"], "sharedEntities": ["EU AI Act"] },
      "severity": "high",
      "observedAt": "2026-03-24T12:00:00.000Z"
    }
  ],
  "pagination": { "total": 34, "limit": 50, "offset": 0, "hasMore": false }
}
Open in Playground →

Clusters

Narrative clusters produced by AIDRAN's topic-level clustering pipeline. The system groups semantically related discourse records into coherent conversation threads, labels each cluster with its dominant terms and a summary, and scores cluster quality. Use clusters to understand the internal structure of a beat — the distinct sub-conversations happening within a broader topic.

GET/api/v1/clustersList clusters

Returns the narrative clusters from the most recent analysis run, each grouping semantically related discourse records into a distinct conversational thread. Every cluster includes its record count, dominant terms, an AI-generated summary label, and quality metadata like silhouette score. Use this to map the sub-conversations within a beat or to identify emerging discussion threads before they become full narratives.

Note: Clusters are regenerated on each analysis run. The metadata.silhouetteScore indicates cluster quality (closer to 1.0 is better).

Parameters

Parameters for List clusters
ParameterTypeRequiredDescription
topicstringoptionalFilter by topic name.
limitintegeroptionalMax clusters returned.Default: 50, max 100

Response Codes

Response codes for List clusters
StatusMeaning
200Success
401Missing or invalid API key
429Rate limit exceeded
curl -H "x-api-key: YOUR_KEY" \
  "https://aidran.ai/api/v1/clusters?topic=ai-safety"
json
{
  "data": [
    {
      "id": 45,
      "runId": "run_2026-03-25_ai-safety",
      "topic": "ai-safety",
      "clusterLabel": 0,
      "recordCount": 34,
      "topTerms": ["alignment", "RLHF", "constitutional"],
      "summaryLabel": "Alignment training approaches",
      "metadata": { "silhouetteScore": 0.62 },
      "createdAt": "2026-03-25T08:00:00.000Z"
    }
  ],
  "count": 5
}
Open in Playground →

System

Operational health and transparency endpoints. Monitor system status, verify ingestion recency, and confirm the pipeline is running — no authentication required.

GET/api/v1/statusSystem status

A public health check that requires no API key. Returns the overall system status, total records in the corpus, 24-hour ingest volume, active topic count, recent signal activity, and the last successful ingestion timestamp for each source platform. Use this to verify the pipeline is running, build status monitors, or confirm data freshness before making further API calls.

Note: This endpoint requires no authentication. It is safe to call from client-side code or public status pages.

Response Codes

Response codes for System status
StatusMeaning
200Success
curl "https://aidran.ai/api/v1/status"
json
{
  "status": "operational",
  "totalRecords": 142853,
  "records24h": 1247,
  "activeTopics": 23,
  "signals48h": 18,
  "sources": [
    { "source": "reddit", "lastIngestion": "2026-03-26T13:00:00.000Z" },
    { "source": "bluesky", "lastIngestion": "2026-03-26T13:30:00.000Z" },
    { "source": "news", "lastIngestion": "2026-03-26T12:00:00.000Z" }
  ],
  "checkedAt": "2026-03-26T14:00:00.000Z"
}
Open in Playground →

Get Started

Ready to build?

Sign up for free and generate an API key instantly. The free tier includes 100 requests per day—enough to evaluate the API and build a prototype.

Get Your API KeyTry the Playground

All API usage is subject to non-commercial terms.