Quick start

Audience: End users

Quick Start Guide

This guide gets you started with the GL Open DeepResearch service using the GL Open DeepResearch Language Binding (gl-odr). You create tasks or task groups with the SDK, then stream events or poll for status and the final result.

Prerequisites

• Python >=3.11,<3.13

• API Key from GL Open DeepResearch Team

• Base URL (default): https://open-deepresearch.glair.ai/

Install the library

pip install gl-odr

Or with uv:

uv add gl-odr

Profile-based usage

GL Open DeepResearch is profile-based: every research request (task or taskgroup) must include a profile name. The profile defines which provider runs (e.g. Tongyi or GPT-Researcher) and with which settings (model, depth, timeouts). You only send the profile name and your query—no provider or model config in the request.

In the steps below we use the ESSENTIAL profile. Available profiles are documented in the API Contract — Profiles. To use a different model (e.g. Claude) or create your own configuration, create a new profile via the Profiles API and then use its name in your SDK calls. For details and an example (create a new profile and use it with Claude), see Research Profiles — Examples.

Step 1: Get Your API Key

Contact the GL Open DeepResearch Team to obtain your API key. Configure it via the api_key argument or the GLODR_API_KEY environment variable.

Step 2: Create a Client and a Task (or Task Group)

Initialize the client and create a single task or a task group with one or more queries.

Python

from gl_odr_sdk import DeepResearchClient

# Use GLODR_API_KEY and optional GLODR_BASE_URL env vars, or pass explicitly
client = DeepResearchClient(api_key="your-api-key")

# Create a single task
task = client.tasks.create(
    query="What are the latest developments in quantum computing?",
    profile="ESSENTIAL",
)
print(f"Task ID: {task.task_id}")

cURL

Task group with one or more queries:

Python

# Create a task group with one query
taskgroup = client.taskgroups.create(
    profile="ESSENTIAL",
    query="What are the latest developments in quantum computing?",
)
print(f"Taskgroup ID: {taskgroup.taskgroup_id}")
print(f"Tasks: {taskgroup.tasks}")

# Or create multiple tasks at once
taskgroup = client.taskgroups.create(
    profile="ESSENTIAL",
    query=[
        "What is AI?",
        "What is machine learning?",
        "What is deep learning?",
    ],
)
print(f"Taskgroup ID: {taskgroup.taskgroup_id}")
print(f"Tasks: {taskgroup.tasks}")

cURL

Note: Save the taskgroup_id and tasks list—you'll need them to track and stream research.

Step 3: Stream Events (optional)

Monitor progress in real time by streaming events for a task or a whole task group.

Stream from a specific task:

Python

# By task ID (works for standalone tasks or tasks in a group)
for event in client.tasks.stream(task.task_id):
    print(f"{event.event_type}: {event.value}")

cURL

Stream from all tasks in a group:

Python

for event in client.taskgroups.stream(taskgroup.taskgroup_id):
    print(f"{event.event_type}: {event.value}")

cURL

Stream one task within a group:

Python

for event in client.taskgroups.stream_task(
    taskgroup_id=taskgroup.taskgroup_id,
    task_id=taskgroup.tasks[0],
):
    print(f"{event.event_type}: {event.value}")

cURL

Event types: THINKING_START, THINKING, THINKING_END, ACTIVITY, RESPONSE. See Structured outputs for details. Events are retained for 24 hours.

Step 4: Get Task Status

Check status without fetching the full result:

Python

# Task status
status = client.tasks.get_status(task.task_id)
print(f"Status: {status.status}")

# Task group status (derived from member tasks)
group = client.taskgroups.get(taskgroup.taskgroup_id)
print(f"Group status: {group.status}")
print(f"Tasks: {group.tasks}")

cURL

Task status values: PENDING, RECEIVED, STARTED, SUCCESS, FAILURE, REVOKED, RETRY.

Task group status values: EMPTY, PENDING, STARTED, SUCCESS, FAILURE, PARTIAL_FAILURE.

Step 5: Get the Final Result

When a task has completed (SUCCESS), retrieve the result:

Python

result = client.tasks.get(task.task_id)
print(f"Status: {result.status}")
if result.data:
    print(f"Result: {result.data.result}")
    print(f"Duration: {result.data.duration}s")

cURL

From a task group:

Python

task_result = client.taskgroups.get_task(
    taskgroup_id=taskgroup.taskgroup_id,
    task_id=taskgroup.tasks[0],
)
if task_result.data:
    print(task_result.data.result)

cURL

Available Profiles

Profile management is described in the API Contract — Profiles. To list or create profiles, use the HTTP API (see api-profiles.md); the SDK focuses on tasks and taskgroups.

Next Steps

• Learn about Research Profiles and Available Open Source Deep Research

• See the Examples for patterns: Simple Deep Research, Run Multiple Queries, Error handling and retries