pip install linkup-sdk            # Python
# or
npm install linkup-sdk            # TypeScript

export LINKUP_API_KEY="your-api-key"

import time
from linkup import LinkupClient

client = LinkupClient(api_key="<YOUR_LINKUP_API_KEY>")

# /research is async: POST returns immediately with an id. Poll until completed.
#
# mode: type of investigation. Setting it explicitly produces the most
# predictable latency, cost, and output shape. If omitted, the agent
# classifies the question and selects one of the three modes for the request.
# - Answer: precise, evidence-backed answer with a definitive solution.
# - Investigate: focused report on a single defined subject. Narrower than Research.
# - Research: structured report organized by theme, covering many topics in parallel.
#
# reasoningDepth (default L): trade latency for thoroughness.
# - S: light coverage, 2-5 min. Short multi-step investigations.
# - M: balanced cost-to-quality, 3-7 min. Routine use.
# - L: thorough investigation, 5-10 min. High-quality answers under bounded latency.
# - XL: exhaustive coverage, 10-20 min. Deliverables where completeness takes precedence over latency.
task = client.research.create(
    q="Compare the 2024 cloud revenue growth of Microsoft, Amazon, and Google.",
    output_type="sourcedAnswer",
    mode="investigate",
    reasoning_depth="L",
)

# Poll: 2-second initial interval, back off to 10s.
interval = 2
while True:
    result = client.research.get(task.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(interval)
    interval = min(interval * 2, 10)

print(result.output)

{
  "type": "function",
  "function": {
    "name": "linkup_research",
    "description": "Submits an autonomous research task and returns a synthesized, cited answer. Use for questions a single search query cannot resolve: verified answers to precise questions, focused investigations of a defined subject, or broad multi-angle reports. Latency is 2-20 minutes depending on reasoningDepth; the handler should poll until completion.",
    "parameters": {
      "type": "object",
      "properties": {
        "q": {
          "type": "string",
          "description": "The research question, phrased in natural language. Both terse and detailed inputs are accepted; more precise input produces more predictable, thorough, and aligned output. Useful dimensions to specify include the angles to cover, the leads to pursue, the facts to verify, the entities to compare, the constraints any answer must satisfy, and the structure expected from the final response. The agent plans and executes the retrieval steps."
        },
        "outputType": {
          "type": "string",
          "enum": ["sourcedAnswer", "structured"],
          "description": "sourcedAnswer for natural-language answer with citations. structured for JSON matching structuredOutputSchema (keep the schema shallow)."
        },
        "structuredOutputSchema": {
          "type": "string",
          "description": "Required when outputType=structured. JSON Schema (as a string) for the response. Root must be type 'object'. Keep flat. Deeply nested arrays of objects multiply latency and failure rate."
        },
        "mode": {
          "type": "string",
          "enum": ["answer", "investigate", "research"],
          "description": "Type of investigation. Setting this field explicitly produces the most predictable latency, cost, and output shape, and is the recommended path. answer for precise, evidence-backed answers with a definitive solution. investigate for a focused report on a single defined subject. research for a structured report organized by theme covering many topics or entities in parallel. If this field is omitted, the agent classifies the question and selects one of the three modes for the request."
        },
        "reasoningDepth": {
          "type": "string",
          "enum": ["S", "M", "L", "XL"],
          "description": "Controls thoroughness, trading latency for coverage. S: light coverage, 2-5 min, suitable for short multi-step investigations. M: balanced cost-to-quality, 3-7 min, suitable for routine use. L (default): thorough investigation, 5-10 min, suitable for high-quality answers under bounded latency. XL: exhaustive coverage, 10-20 min, suitable for deliverables where completeness takes precedence over latency. Match the depth to budget, latency requirements, and the complexity of the request.",
          "default": "L"
        },
        "includeDomains": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Restrict the search to up to 100 trusted domains. Strongly recommended. Improves quality and reduces latency."
        },
        "excludeDomains": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Domains to exclude."
        },
        "fromDate": {
          "type": "string",
          "description": "ISO 8601 (YYYY-MM-DD). Restrict to results on or after this date."
        },
        "toDate": {
          "type": "string",
          "description": "ISO 8601 (YYYY-MM-DD). Restrict to results on or before this date."
        }
      },
      "required": ["q", "outputType"]
    }
  }
}