Session Result

curl --request GET \
  --url https://api.example.com/sessions/{session_id}/result

{
  "session_id": "<string>",
  "business_plan": {
    "problem": "<string>",
    "icp": "<string>",
    "solution": "<string>",
    "market": "<string>",
    "business_model": "<string>",
    "channels": "<string>",
    "risks": [
      "<string>"
    ],
    "citations": [
      {
        "source_url": "<string>",
        "chunk_index": 123,
        "similarity": 0.5,
        "provenance": {
          "provider_name": "tavily",
          "provider_kind": "free",
          "payment": {
            "intent_id": "<string>",
            "tx_signature": "<string>",
            "facilitator_id": "<string>",
            "network": "<string>",
            "error": "<string>"
          }
        },
        "creator_handle": "<string>",
        "creator_payout_usd": 123,
        "creator_wallet": "<string>"
      }
    ]
  },
  "validation_report": {
    "market_size_signal": "<string>",
    "competitor_analysis": "<string>",
    "demand_evidence": "<string>",
    "risk_flags": [
      "<string>"
    ],
    "citations": [
      {
        "source_url": "<string>",
        "chunk_index": 123,
        "similarity": 0.5,
        "provenance": {
          "provider_name": "tavily",
          "provider_kind": "free",
          "payment": {
            "intent_id": "<string>",
            "tx_signature": "<string>",
            "facilitator_id": "<string>",
            "network": "<string>",
            "error": "<string>"
          }
        },
        "creator_handle": "<string>",
        "creator_payout_usd": 123,
        "creator_wallet": "<string>"
      }
    ],
    "gap_classification": "Partial:segment",
    "gap_summary": "",
    "gap_explanation": "<string>"
  },
  "prd": {
    "v1_scope": [
      "<string>"
    ],
    "v2_scope": [
      "<string>"
    ],
    "v3_scope": [
      "<string>"
    ],
    "acceptance_criteria": [
      "<string>"
    ],
    "non_functional": [
      "<string>"
    ],
    "success_metrics": [
      "<string>"
    ],
    "citations": [
      {
        "source_url": "<string>",
        "chunk_index": 123,
        "similarity": 0.5,
        "provenance": {
          "provider_name": "tavily",
          "provider_kind": "free",
          "payment": {
            "intent_id": "<string>",
            "tx_signature": "<string>",
            "facilitator_id": "<string>",
            "network": "<string>",
            "error": "<string>"
          }
        },
        "creator_handle": "<string>",
        "creator_payout_usd": 123,
        "creator_wallet": "<string>"
      }
    ]
  },
  "sources": [
    {
      "url": "<string>",
      "chunk_count": 1,
      "indexed_at": "2023-11-07T05:31:56Z"
    }
  ],
  "transcript": {},
  "pro_session_summary": "<string>",
  "verdict": "REFINE",
  "low_grounding": false,
  "low_explanation": false,
  "verdict_hash": "<string>",
  "per_voice": {
    "voices": [
      {
        "position": "<string>",
        "tension": "<string>",
        "recommendation": "<string>"
      }
    ]
  },
  "transcript_summary": "<string>",
  "market_landscape": {
    "competitors": [
      {
        "name": "<string>",
        "what_they_do": "<string>",
        "why_we_are_not_them": "<string>",
        "flag": "<string>"
      }
    ]
  },
  "surviving_dissent": {
    "dissents": [
      {
        "verbatim": "<string>",
        "on_topic": "<string>"
      }
    ],
    "rationale": ""
  },
  "next_steps_with_falsifiers": {
    "steps": [
      {
        "action": "<string>",
        "falsifier": {
          "what_would_disprove_this": "<string>",
          "by_when": "<string>"
        }
      }
    ]
  },
  "calibration_corpus": "<string>",
  "refinement": {
    "refined_statement": "<string>",
    "addresses_dissent": [
      {
        "dissent_quote": "<string>",
        "resolution": "<string>"
      }
    ],
    "new_falsifiers_now_harder": [
      "<string>"
    ],
    "what_it_no_longer_claims": [
      "<string>"
    ],
    "what_it_now_claims_instead": [
      "<string>"
    ]
  },
  "advisor_panel": {},
  "cited_doc_ids": [
    "<string>"
  ],
  "citation_markers": [
    {
      "idx": 2,
      "doc_id": "<string>",
      "url": "<string>",
      "span": "<string>"
    }
  ],
  "confidence": 0,
  "degraded_sections": [
    "<string>"
  ],
  "degraded_reasons": {}
}

API Reference

Session Result

Poll for the async ResearchResult.

Polling contract (this is the public contract for the CLI, the web app, and any third-party consumer):

Clients poll this endpoint after POST /research returns {"status": "processing", "poll_url": ...}.
The recommended retry interval is 3 seconds. The CLI uses 3s; the body also surfaces retry_after_seconds as a hint when we’ve decided a longer back-off is appropriate.
The 425 response IS the documented “still working” signal — it is NOT an error. A typical 60-second basic-tier session will emit roughly 20 successive 425 responses before flipping to 200. Operators: those 425s are downgraded to DEBUG in the access log by gecko_api.access_log_filter; if you’re seeing them flood INFO logs, that filter isn’t installed.
Stop polling on any of: 200, 4xx, 5xx, 410.

Status code semantics:

200 + ResearchResult JSON : workflow complete (terminal)
425 Too Early : still processing — retry in ~retry_after_seconds seconds
500 + : workflow raised — terminal
410 Gone + : session was killed by a container shutdown mid-flight (ECS rolling deploy / autoscale). Re-submit the original request to start a fresh session.
404 : session not found / soft-deleted
400 : session_id is not a UUID

GET

sessions

{session_id}

result

Session Result

curl --request GET \
  --url https://api.example.com/sessions/{session_id}/result

{
  "session_id": "<string>",
  "business_plan": {
    "problem": "<string>",
    "icp": "<string>",
    "solution": "<string>",
    "market": "<string>",
    "business_model": "<string>",
    "channels": "<string>",
    "risks": [
      "<string>"
    ],
    "citations": [
      {
        "source_url": "<string>",
        "chunk_index": 123,
        "similarity": 0.5,
        "provenance": {
          "provider_name": "tavily",
          "provider_kind": "free",
          "payment": {
            "intent_id": "<string>",
            "tx_signature": "<string>",
            "facilitator_id": "<string>",
            "network": "<string>",
            "error": "<string>"
          }
        },
        "creator_handle": "<string>",
        "creator_payout_usd": 123,
        "creator_wallet": "<string>"
      }
    ]
  },
  "validation_report": {
    "market_size_signal": "<string>",
    "competitor_analysis": "<string>",
    "demand_evidence": "<string>",
    "risk_flags": [
      "<string>"
    ],
    "citations": [
      {
        "source_url": "<string>",
        "chunk_index": 123,
        "similarity": 0.5,
        "provenance": {
          "provider_name": "tavily",
          "provider_kind": "free",
          "payment": {
            "intent_id": "<string>",
            "tx_signature": "<string>",
            "facilitator_id": "<string>",
            "network": "<string>",
            "error": "<string>"
          }
        },
        "creator_handle": "<string>",
        "creator_payout_usd": 123,
        "creator_wallet": "<string>"
      }
    ],
    "gap_classification": "Partial:segment",
    "gap_summary": "",
    "gap_explanation": "<string>"
  },
  "prd": {
    "v1_scope": [
      "<string>"
    ],
    "v2_scope": [
      "<string>"
    ],
    "v3_scope": [
      "<string>"
    ],
    "acceptance_criteria": [
      "<string>"
    ],
    "non_functional": [
      "<string>"
    ],
    "success_metrics": [
      "<string>"
    ],
    "citations": [
      {
        "source_url": "<string>",
        "chunk_index": 123,
        "similarity": 0.5,
        "provenance": {
          "provider_name": "tavily",
          "provider_kind": "free",
          "payment": {
            "intent_id": "<string>",
            "tx_signature": "<string>",
            "facilitator_id": "<string>",
            "network": "<string>",
            "error": "<string>"
          }
        },
        "creator_handle": "<string>",
        "creator_payout_usd": 123,
        "creator_wallet": "<string>"
      }
    ]
  },
  "sources": [
    {
      "url": "<string>",
      "chunk_count": 1,
      "indexed_at": "2023-11-07T05:31:56Z"
    }
  ],
  "transcript": {},
  "pro_session_summary": "<string>",
  "verdict": "REFINE",
  "low_grounding": false,
  "low_explanation": false,
  "verdict_hash": "<string>",
  "per_voice": {
    "voices": [
      {
        "position": "<string>",
        "tension": "<string>",
        "recommendation": "<string>"
      }
    ]
  },
  "transcript_summary": "<string>",
  "market_landscape": {
    "competitors": [
      {
        "name": "<string>",
        "what_they_do": "<string>",
        "why_we_are_not_them": "<string>",
        "flag": "<string>"
      }
    ]
  },
  "surviving_dissent": {
    "dissents": [
      {
        "verbatim": "<string>",
        "on_topic": "<string>"
      }
    ],
    "rationale": ""
  },
  "next_steps_with_falsifiers": {
    "steps": [
      {
        "action": "<string>",
        "falsifier": {
          "what_would_disprove_this": "<string>",
          "by_when": "<string>"
        }
      }
    ]
  },
  "calibration_corpus": "<string>",
  "refinement": {
    "refined_statement": "<string>",
    "addresses_dissent": [
      {
        "dissent_quote": "<string>",
        "resolution": "<string>"
      }
    ],
    "new_falsifiers_now_harder": [
      "<string>"
    ],
    "what_it_no_longer_claims": [
      "<string>"
    ],
    "what_it_now_claims_instead": [
      "<string>"
    ]
  },
  "advisor_panel": {},
  "cited_doc_ids": [
    "<string>"
  ],
  "citation_markers": [
    {
      "idx": 2,
      "doc_id": "<string>",
      "url": "<string>",
      "span": "<string>"
    }
  ],
  "confidence": 0,
  "degraded_sections": [
    "<string>"
  ],
  "degraded_reasons": {}
}

Path Parameters

session_id

string

required

Response

Successful Response

Result of a full research() workflow.

session_id

string

required

tier

enum<string>

required

Available options:

basic,

pro

business_plan

BusinessPlan · object

required

One-page business plan for the idea.

Show child attributes

validation_report

ValidationReport · object

required

Quantified validation of the idea.

Show child attributes

prd

PRD · object

required

V1/V2/V3 scoped product requirements document.

Show child attributes

sources

SourceInfo · object[]

required

Show child attributes

transcript

Transcript · object

pro_session_summary

string | null

verdict

enum<string>

default:REFINE

S11-VERDICT-01 / S17-TONE-01 / S20-COHERENCE-VERDICT-LABEL-01 — single-token go/no-go signal surfaced to founders.

Derived from the structured gap_classification plus advisor consensus (when available) plus the pro-tier coherence-flag count. The typed gap stays as evidence — Verdict is the headline.

Mapping rule (see derive_verdict):

≥2 critic/voice flags of incoherent_premise → KILL (pro-tier only)
Full or False → PIVOT
Partial:pricing / Partial:integration AND advisor_consensus ≥ 0.8 → GO else → REFINE
Partial:segment | UX | geo → REFINE

S17-TONE-01 — vocabulary softened: KILL → PIVOT (same semantics, framed as a redirect rather than a kill); BUILD → GO (more energizing, shorter). REFINE is unchanged.

S20-COHERENCE-VERDICT-LABEL-01 — KILL is RE-INTRODUCED with refined semantics distinct from the legacy v1 token. The legacy KILL meant "weak idea, don't build as-is" and was renamed to PIVOT in S17. The new KILL means "premise is INCOHERENT or unverifiable; no amount of refinement saves it" — the dog-emotional-AI-blockchain class of idea where the wedge can't be made real because the components don't compose. Trigger condition is structural: ≥2 voices in the 5-agent pro-tier debate flag incoherent_premise. Basic tier never emits KILL (no debate to count flags from). The _missing_ hook below maps the LEGACY "KILL" string still present in older result_json rows / on-disk transcripts to PIVOT (their actual semantic), NOT to the new KILL — the fresh KILL only ever comes from the synthesizer's coherence-flag count, never from an upstream string. The 20260502120000 migration backfills the JSONB rows for clean read paths; the shim is defense in depth for any row written by an older deploy mid-rollout or by an external SDK consumer that pinned an older Verdict value.

Available options:

PIVOT,

REFINE,

GO,

KILL

low_grounding

boolean

default:false

low_explanation

boolean

default:false

provider_mix_flag

enum<string> | null

Available options:

balanced,

single_provider_dominates,

thin_diversity

verdict_hash

string | null

per_voice

PerVoiceReadout · object

Show child attributes

transcript_summary

string | null

market_landscape

MarketLandscape · object

Show child attributes

surviving_dissent

SurvivingDissent · object

Show child attributes

next_steps_with_falsifiers

NextStepsWithFalsifiers · object

Show child attributes

calibration_corpus

string | null

idea_classification

enum<string> | null

Available options:

greenfield,

iterative,

unclear

founder_posture

enum<string> | null

Available options:

high,

moderate,

unclear

refinement

RefinedIdea · object

Show child attributes

advisor_panel

Advisor Panel · object

cited_doc_ids

string[]

citation_markers

CitationMarker · object[]

Show child attributes

confidence

number

default:0

Required range: 0 <= x <= 1

degraded_sections

string[]

degraded_reasons

Degraded Reasons · object

Show child attributes

Sources Session Economics

⌘I