> ## Documentation Index > Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt > Use this file to discover all available pages before exploring further. # Trace, RAG & Async Models > Data models for traces, spans, messages, RAG retrieval, and async job handling. ## Async Job Models ### `AsyncJobHandle` Generic async job handle used by failure analysis and other modules. Wraps polling, cancellation, and result retrieval. | Property/Method | Return Type | Description | | ------------------------------------------- | ---------------- | ------------------------------------------------------------------------ | | `job_id` | `str` | Job identifier. | | `job_type` | `str` | Job type string. | | `status()` | `AsyncJobStatus` | Poll current status. | | `is_running()` | `bool` | Whether still running. | | `is_completed()` | `bool` | Whether completed. | | `cancel()` | `Dict[str, Any]` | Cancel the job. | | `result()` | `Any` | Block until complete and return result. Raises `RuntimeError` if failed. | | `wait(poll_interval, timeout, on_progress)` | `AsyncJobStatus` | Poll with progress callback. Raises `TimeoutError` if exceeded. | **`wait()` parameters:** | Parameter | Type | Default | Description | | --------------- | -------------------- | ------- | ---------------------------------------------- | | `poll_interval` | `float` | `2.0` | Seconds between polls. | | `timeout` | `Optional[float]` | `None` | Max wait time in seconds. `None` = no timeout. | | `on_progress` | `Optional[Callable]` | `None` | Callback receiving `AsyncJobStatus`. | ### `AsyncJobStatus` | Field | Type | Description | | ------------------ | --------------- | ---------------------------------------------------------------------------------- | | `job_id` | `str` | Job identifier. | | `job_type` | `str` | Job type. | | `status` | `str` | `"queued"`, `"running"`, `"processing"`, `"completed"`, `"failed"`, `"cancelled"`. | | `progress_percent` | `float` | Progress (0–100). | | `current_item` | `int` | Current item. | | `total_items` | `int` | Total items. | | `started_at` | `Optional[str]` | ISO timestamp. | | `finished_at` | `Optional[str]` | ISO timestamp. | | `error` | `Optional[str]` | Error message. | **Properties:** `is_running`, `is_completed`, `is_failed`. *** ## Trace Models ### `TraceRecord` A trace summary in a list response. | Field | Type | Description | | ---------------- | ----------------- | ------------------------------- | | `trace_id` | `str` | Trace identifier. | | `project_id` | `str` | Project ID. | | `status` | `str` | Trace status. | | `session_id` | `Optional[str]` | Session identifier. | | `project_name` | `Optional[str]` | Project name. | | `app_name` | `Optional[str]` | Application name. | | `duration_ms` | `Optional[float]` | Total duration in milliseconds. | | `total_cost` | `Optional[float]` | Estimated cost in USD. | | `total_tokens` | `Optional[int]` | Total tokens used. | | `llm_calls` | `Optional[int]` | Number of LLM calls. | | `tool_calls` | `Optional[int]` | Number of tool calls. | | `input_preview` | `Optional[str]` | Truncated input text. | | `output_preview` | `Optional[str]` | Truncated output text. | | `eval_available` | `bool` | Whether evaluation data exists. | | `created_at` | `Optional[str]` | ISO timestamp. | ### `TraceListResponse` Paginated list of traces. Supports `len()` and iteration. | Field | Type | | ----------- | ------------------- | | `traces` | `List[TraceRecord]` | | `total` | `int` | | `page` | `int` | | `page_size` | `int` | ### `TraceOverview` Basic trace information. | Field | Type | | ------------- | ----------------- | | `trace_id` | `str` | | `status` | `str` | | `duration_ms` | `Optional[float]` | | `total_cost` | `Optional[float]` | | `llm_calls` | `Optional[int]` | | `tool_calls` | `Optional[int]` | ### `TraceSummary` Detailed trace summary with full metadata. | Field | Type | Description | | ----------------- | --------------------- | ------------------------- | | `trace_id` | `str` | Trace identifier. | | `project_id` | `str` | Project ID. | | `status` | `str` | Trace status. | | `duration_ms` | `Optional[float]` | Duration in milliseconds. | | `total_cost` | `Optional[float]` | Estimated cost. | | `total_tokens` | `Optional[int]` | Total tokens. | | `input_tokens` | `Optional[int]` | Input tokens. | | `output_tokens` | `Optional[int]` | Output tokens. | | `llm_calls` | `Optional[int]` | LLM call count. | | `tool_calls` | `Optional[int]` | Tool call count. | | `retrieval_calls` | `Optional[int]` | Retrieval call count. | | `message_count` | `int` | Number of messages. | | `span_count` | `int` | Number of spans. | | `tags` | `Optional[List[str]]` | Trace tags. | | `custom_fields` | `Optional[Dict]` | Custom metadata. | ### `TraceMessage` A message in a trace's conversation. | Field | Type | | -------------- | ---------------------- | | `role` | `str` | | `content` | `str` | | `timestamp` | `Optional[str]` | | `tool_calls` | `Optional[List[Dict]]` | | `tool_call_id` | `Optional[str]` | | `name` | `Optional[str]` | ### `TraceSpan` A span in a trace's execution tree. | Field | Type | | ---------------- | ---------------------- | | `span_id` | `str` | | `name` | `str` | | `kind` | `str` | | `parent_span_id` | `Optional[str]` | | `start_time` | `Optional[str]` | | `end_time` | `Optional[str]` | | `duration_ms` | `Optional[float]` | | `status` | `Optional[str]` | | `attributes` | `Dict[str, Any]` | | `events` | `List[Dict[str, Any]]` | ### `TraceFullResult` Complete trace data including messages, spans, retrievals, and execution tree. | Field | Type | | ---------------- | ---------------------- | | `trace_id` | `str` | | `metadata` | `Dict[str, Any]` | | `summary` | `Dict[str, Any]` | | `messages` | `List[Dict[str, Any]]` | | `spans` | `Dict[str, Any]` | | `retrievals` | `List[Dict[str, Any]]` | | `diagnostics` | `Optional[Dict]` | | `execution_tree` | `Optional[Dict]` | ### `TraceEvalStep` An evaluation step computed from a trace. | Field | Type | | ------------- | ----------------- | | `metric` | `str` | | `score` | `Optional[float]` | | `explanation` | `Optional[str]` | | `status` | `str` | | `input_text` | `Optional[str]` | | `output_text` | `Optional[str]` | | `context` | `Optional[str]` | *** ## RAG Models ### `DocumentHit` A document match from a retrieval step. | Field | Type | Description | | ----------------- | --------------------- | ----------------------------------- | | `doc_id` | `str` | Document identifier. | | `rank` | `int` | Rank position. | | `score` | `float` | Similarity/relevance score. | | `span` | `Optional[List[int]]` | `[start, end]` character positions. | | `snippet_preview` | `Optional[str]` | First 200 characters. | | `metadata` | `Optional[Dict]` | Custom document metadata. | ### `RetrievalInfo` Information about a retrieval step. | Field | Type | Description | | ---------------------- | ----------------------------- | ------------------------------------------------------------ | | `retriever` | `str` | Retriever type: `"vectordb"`, `"bm25"`, `"api"`, `"hybrid"`. | | `embedding_model` | `Optional[str]` | Embedding model used. | | `chunk_size` | `Optional[int]` | Chunk size in tokens. | | `chunk_overlap` | `Optional[int]` | Chunk overlap. | | `top_k` | `Optional[int]` | Number of results requested. | | `similarity_threshold` | `Optional[float]` | Minimum similarity score. | | `query` | `Optional[str]` | The retrieval query. | | `hits` | `Optional[List[DocumentHit]]` | Retrieved documents. | | `latency_ms` | `Optional[float]` | Retrieval latency. | ### `Citation` A citation linking a generated answer to a source document. | Field | Type | | ----------------- | --------------------- | | `doc_id` | `str` | | `span` | `Optional[List[int]]` | | `confidence` | `Optional[float]` | | `relevance_score` | `Optional[float]` | ### `GenerationInfo` Information about a generation step. | Field | Type | Description | | ----------------------- | -------------------------- | ----------------------- | | `answer` | `str` | Generated answer. | | `citations` | `Optional[List[Citation]]` | Source citations. | | `format_check` | `Optional[FormatCheck]` | Output format analysis. | | `model_used` | `Optional[str]` | Model used. | | `prompt_template` | `Optional[str]` | Template used. | | `context_length` | `Optional[int]` | Context window used. | | `generation_latency_ms` | `Optional[float]` | Generation latency. | | `reasoning_trace` | `Optional[List[str]]` | Reasoning steps. | ### `FormatCheck` Output format analysis. | Field | Type | Default | | -------------------- | --------------- | ------- | | `is_complete` | `bool` | `True` | | `length_tokens` | `Optional[int]` | `None` | | `length_chars` | `Optional[int]` | `None` | | `refusal` | `bool` | `False` | | `contains_citations` | `bool` | `False` | | `citation_count` | `Optional[int]` | `None` | | `language` | `Optional[str]` | `None` | | `format_type` | `Optional[str]` | `None` | *** ## Related * [TraceQueryClient](/sdk/trace-query-client) — Methods returning trace models * [Tracer](/sdk/tracer) — Methods using RAG models * [Evaluation Models](/sdk/models/evaluation) — Eval data models