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)
GET /api/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 /api/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 /api/v1/sessions/{id}
Session details with operations, context_summary, access_level (owner/org_viewer/public), user_organizations.
PATCH /api/v1/sessions/{id}
Update: name, description, intent_context, config.
DELETE /api/v1/sessions/{id}
Delete session and all operations (permanent).
POST /api/v1/sessions/{id}/complete
Mark completed. Prevents new operations.
POST /api/v1/sessions/{id}/archive
Archive a completed session.
POST /api/v1/sessions/{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 /api/v1/sessions/{id}/timeline
Chronological timeline of all operations with status, results, credits.
GET /api/v1/sessions/{id}/link-graph
Aggregated link graph across all session crawls. FREE.
| Parameter | Default | Description |
|---|---|---|
include_nodes | true | Include node data |
include_edges | false | Include edge data |
node_limit | 100 | Max nodes (1-1000) |
sort_by | pagerank | pagerank, inlinks, authority, hub |
min_importance | 0 | Min PageRank filter |
metadata_only | false | Only cached stats (faster) |
Response: link_graph.stats (total_nodes, total_edges, operations_included, total_pages_crawled), domain_authority, hubs[], authorities[], nodes[], last_updated.
See Crawl API - Link Graph for field details.
POST /api/v1/sessions/{id}/search
Search within session. Same params as POST /api/v1/search plus filter_seen_urls (bool, default false).
POST /api/v1/sessions/{id}/crawl
Crawl within session. Same params as POST /api/v1/crawls plus filter_seen_urls (bool, default true).
GET /api/v1/public/sessions/{id}
View publicly shared session (no auth).
GET /api/v1/public/sessions/{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 × 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) |