---
title: "Generate a structured, sourced market research brief on any market, sector or industry. Returns a machine-readable note"
method: POST
path: "/api/v1/call/market_research_brief"
tags: ["data", "expertise"]
---

# Generate a structured, sourced market research brief on any market, sector or industry. Returns a machine-readable note

`POST /api/v1/call/market_research_brief`

## Request

- Base URL: `https://mcp.gapup.io`
- URL: `https://mcp.gapup.io/api/v1/call/market_research_brief`
- Auth: HTTP bearer

Generate a structured, sourced market research brief on any market, sector or industry. Returns a machine-readable note with six sections: an executive overview, a market-size estimate (with assumptions and sources — no invented figures), key players, demand & technology trends, risk factors, and a traceable source list. When to use this tool: an agent needs to assess a new market, validate a business opportunity, prepare a pitch, or benchmark a sector before a strategic decision. Data is assembled live from keyless public sources: Wikipedia (sector context), World Bank (macro GDP/population for market sizing), REST Countries (geo context). Fields that cannot be sourced are marked 'unavailable' rather than estimated. Inputs: topic (required), geo and sector (optional refinements).

## Request body

- object
  - `topic` string, required: Market or sector to research (e.g. 'electric vehicle batteries', 'B2B SaaS CRM Europe', 'telemedicine Africa')
  - `geo` string: Optional geography to scope the brief (country name, region, or continent — e.g. 'France', 'Southeast Asia')
  - `sector` string: Optional parent sector to disambiguate the topic (e.g. 'healthcare', 'energy', 'software')
  - `async` boolean: If true, returns a job_id immediately (<200ms) instead of waiting for the result. Poll the result with job_result(job_id). Use for slow tools to avoid client timeouts.

## Response `200`

Tool result

- object
  - `tool` string
  - `result` object
    - `topic` string, required
    - `geo` unknown, required
    - `sector` unknown, required
    - `generated_at` string, required: ISO-8601 timestamp of generation
    - `overview` object, required: Executive summary of the market
      - `summary` string, required
      - `wikipedia_title` unknown
      - `wikipedia_url` unknown
    - `market_size_estimate` object, required: Market size estimate with hypotheses. All figures sourced or marked unavailable.
      - `geo_context` object: Country/region macro context used in sizing
        - `country` string, required
        - `region` unknown
        - `gdp_usd` unknown
        - `gdp_year` unknown
        - `population` unknown
        - `population_year` unknown
        - `gdp_source` string, required
      - `stated_market_size` object: Any market size figure found in public data (Wikidata P2139)
        - `amount_usd` unknown
        - `year_found` unknown
        - `source` string
        - `caveat` string
      - `methodology_note` string, required: How the estimate was derived or why it is unavailable
    - `key_players` object, required
      - `note` string, required
      - `players` object[], required
        - `name` string, required
        - `description` unknown
      - `source` unknown
    - `trends` object, required
      - `note` string, required
      - `items` object[], required
        - `trend` string, required
        - `source` unknown
    - `risks` object, required
      - `note` string, required
      - `items` object[], required
        - `risk` string, required
        - `severity` 'high' | 'medium' | 'low' | 'unknown', required
    - `sources` object[], required: All sources consulted, with URL and retrieval status
      - `label` string, required
      - `url` string, required
      - `status` 'retrieved' | 'unavailable' | 'partial', required
  - `request_id` string
  - `source` 'rest-api'
  - `ms` number

## Other responses

- `400`: Invalid arguments
- `401`: Unauthorized
- `402`: Payment Required — pay via x402 (USDC on Base) then retry with X-Payment header
- `404`: Tool not found
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api.md) · [All operations](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/revisions/afb9da3b98f4?raw)