Research runs are NoodleSpy's core feature. You submit a topic, NoodleSpy discovers sources, reads and analyzes them, and returns structured findings with themes, quotes, and source attribution.
Research runs are async. You create a run, then poll for results.
POST /runs
Costs 1–3 research credits depending on depth (quick = 1, standard = 2, deep = 3). Credits are only consumed when the run completes successfully — failed runs are refunded.
{
"topic": "user onboarding pain points in B2B SaaS",
"research_type": "topic_research",
"sources": ["reddit"],
"options": {
"depth": "standard",
"time_range": "recent",
"focus": "pain_points",
"raw": false
}
}
| Field | Type | Required | Description |
|---|---|---|---|
topic | string | yes | The research topic |
research_type | string | no | topic_research (default) |
sources | string[] | no | Source platforms: reddit |
options.depth | string | no | quick (1 credit), standard (2), deep (3). Default: standard |
options.time_range | string | no | recent, year, any. Default: recent |
options.focus | string | no | general, pain_points, solutions, opinions. Default: general |
options.raw | boolean | no | Skip synthesis, return raw source content. Default: false |
{
"data": {
"id": "run_abc123",
"topic": "user onboarding pain points in B2B SaaS",
"research_type": "topic_research",
"sources": ["reddit"],
"options": {
"depth": "standard",
"time_range": "recent",
"focus": "pain_points"
},
"status": "queued",
"created_at": "2026-03-18T10:30:00Z",
"updated_at": "2026-03-18T10:30:00Z"
}
}
GET /runs/{id}
Poll this endpoint to check status and retrieve findings when complete.
{
"data": {
"id": "run_abc123",
"topic": "user onboarding pain points in B2B SaaS",
"status": "completed",
"findings": {
"summary": "Users consistently report frustration with lengthy onboarding...",
"themes": [
{
"name": "Too many onboarding steps",
"description": "Users abandon flows with more than 5 steps",
"sentiment": "negative",
"frequency": 12,
"quote_ids": ["q_1", "q_2"]
}
],
"quotes": [
{
"id": "q_1",
"text": "The onboarding wizard has 14 steps and I gave up on step 3",
"author": "frustrated_user",
"source_url": "https://reddit.com/r/SaaS/...",
"platform": "reddit",
"community": "r/SaaS",
"date": "2026-02-10",
"themes": ["Too many onboarding steps"]
}
],
"sources": [
{
"url": "https://reddit.com/r/SaaS/...",
"title": "Why do SaaS onboarding flows suck?",
"platform": "reddit",
"community": "r/SaaS",
"relevance": 0.92
}
],
"metadata": {
"mode": "synthesized",
"sources_discovered": 24,
"sources_analyzed": 8,
"generated_at": "2026-03-18T10:38:00Z"
}
},
"started_at": "2026-03-18T10:30:05Z",
"completed_at": "2026-03-18T10:38:00Z"
}
}
| Status | Meaning |
|---|---|
queued | Run is waiting to start |
running | Research is in progress |
completed | Findings are ready |
failed | Something went wrong (check error field) |
GET /runs
Returns a paginated list of your research runs.
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: queued, running, completed, failed |
limit | integer | Results per page (default 20) |
cursor | string | Pagination cursor from previous response |
{
"data": [
{
"id": "run_abc123",
"topic": "user onboarding pain points in B2B SaaS",
"status": "completed",
"created_at": "2026-03-18T10:30:00Z",
"updated_at": "2026-03-18T10:38:00Z"
}
],
"next_cursor": "eyJ0..."
}
Themes are recurring patterns discovered across sources.
| Field | Type | Description |
|---|---|---|
name | string | Short theme name |
description | string | Explanation of the theme |
sentiment | string | Overall sentiment (positive, negative, neutral, mixed) |
frequency | integer | How many sources mention this theme |
quote_ids | string[] | IDs of quotes supporting this theme |
Direct quotes from source material with full attribution.
| Field | Type | Description |
|---|---|---|
id | string | Unique quote ID |
text | string | The quoted text |
author | string | Author username |
source_url | string | URL of the source |
platform | string | Platform (e.g., reddit) |
community | string | Community (e.g., r/SaaS) |
date | string | Date of the post |
context | string | Surrounding context |
themes | string[] | Themes this quote relates to |
Pages that were discovered and analyzed.
| Field | Type | Description |
|---|---|---|
url | string | Source URL |
title | string | Page title |
platform | string | Platform |
community | string | Community |
relevance | number | Relevance score (0–1) |
raw: true)When you set options.raw to true, findings include raw_content instead of synthesized themes:
{
"raw_content": [
{
"source_url": "https://reddit.com/r/SaaS/...",
"title": "Why do SaaS onboarding flows suck?",
"platform": "reddit",
"community": "r/SaaS",
"author": "startup_founder",
"date": "2026-02-10",
"body": "I've been evaluating 20 different SaaS products...",
"comments": [
{
"author": "frustrated_user",
"text": "The onboarding wizard has 14 steps...",
"score": 142,
"date": "2026-02-10"
}
]
}
]
}