Sessions API
Multi-step agent research with automatic URL deduplication, credit tracking, and context inheritance. Sessions give agents memory across patrols.
Lifecycle: active -> completed -> archived
Credits: Same as individual operations (search/crawl/ask)
GET /v1/sessions
List sessions. Query: limit (1-100), offset, status, tag, days_back, include_shared (includes org-shared sessions, returns separate shared_sessions[] and user_organizations[]).
POST /v1/sessions
| Parameter | Type | Default | Description |
|---|---|---|---|
name | String | required | Session name (max 255 chars) |
description | String | - | Optional description |
intent_context | String | - | Monitoring intent guiding agent behavior |
session_config.auto_deduplicate | Bool | true | Auto-remove duplicate URLs |
session_config.accumulate_context | Bool | true | Build context from previous operations |
session_config.use_session_context | Bool | true | Use context for AI features |
session_config.max_operations | Int | - | Operation limit (1-100) |
metadata.intent.type | String | - | competitive_analysis, due_diligence, technical_evaluation, market_research, academic_research, news_monitoring, lead_generation |
Limits: 100 sessions/user, 1-100 operations/session, auto-archive after 7 days
GET /v1/sessions/{session_id}
Session details with operations, context_summary, access_level (owner/org_viewer/public), user_organizations.
PATCH /v1/sessions/{session_id}
Update: name, description, intent_context, config.
DELETE /v1/sessions/{session_id}
Delete session and all operations (permanent).
POST /v1/sessions/{session_id}/complete
Mark completed. Prevents new operations.
POST /v1/sessions/{session_id}/archive
Archive a completed session.
POST /v1/sessions/{session_id}/share
Toggle sharing. Body: public_share (bool), shared_with_org (bool), organization_id (required when sharing with org).
Cascade: Org sharing changes propagate to all child operations (search jobs, crawls).
GET /v1/sessions/{session_id}/timeline
Chronological timeline of all operations with status, results, credits.
Session Operations
POST /v1/sessions/{session_id}/search
Search within session context. Same params as POST /v1/searches plus filter_seen_urls (bool, default false).
POST /v1/sessions/{session_id}/crawl
Crawl within session context. Same params as POST /v1/crawls plus filter_seen_urls (bool, default true).
POST /v1/sessions/{session_id}/ask
Ask within session context. Same params as POST /v1/asks.
Public Endpoints
GET /v1/public/sessions/{session_id}
View publicly shared session (no auth).
GET /v1/public/sessions/{session_id}/timeline
View public session timeline (no auth).
Session Context for Agent Features
When use_session_context: true, agents receive accumulated context: Monitoring Intent, Recent Queries, Document/Content Types, Domain Frequency, Entities & Keywords.
Intent Types & Effects
| Intent Type | Query Additions | Reranking Boost |
|---|---|---|
competitive_analysis | "vs", "comparison" | +20% news, analyst reports |
due_diligence | "risks", "financials" | +20% legal, regulatory |
technical_evaluation | "benchmarks", "specs" | +20% documentation |
academic_research | "research", "paper" | +20% academic writing |
Reranking: Authority alignment (1.25x), document type match (1.15x), novelty scoring (exp(-0.15 x domain_count)).
URL Deduplication vs Novelty Reranking
| Aspect | filter_seen_urls=true | rerank_results=true |
|---|---|---|
| Type | Hard filter | Soft penalty |
| Timing | Before results | During reranking |
| Scope | Exact URL | URLs + domain frequency |
| Credits | Free | Triggers advanced (2 credits) |