> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-devupd-1765394015-eccef47.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Run (span) data format
Before diving into this content, it might be helpful to read the following:
* [Conceptual guide on tracing and runs](/langsmith/observability-concepts)
LangSmith stores and processes trace data in a simple format that is easy to export and import.
Many of these fields are optional or not important to know about but are included for completeness. The **bolded** fields are the most important ones to know about.
| Field Name | Type | Description |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **id** | UUID | Unique identifier for the span. |
| **name** | string | The name associated with the run. |
| **inputs** | object | A map or set of inputs provided to the run. |
| **run\_type** | string | Type of run, e.g., "llm", "chain", "tool". |
| **start\_time** | datetime | Start time of the run. |
| **end\_time** | datetime | End time of the run. |
| **extra** | object | Any extra information run. |
| **error** | string | Error message if the run encountered an error. |
| **outputs** | object | A map or set of outputs generated by the run. |
| **events** | array of objects | A list of event objects associated with the run. This is relevant for runs executed with streaming. |
| **tags** | array of strings | Tags or labels associated with the run. |
| **trace\_id** | UUID | Unique identifier for the trace the run is a part of. This is also the `id` field of the root run of the trace |
| **dotted\_order** | string | Ordering string, hierarchical. Format: `run_start_time`Z`run_uuid`.`child_run_start_time`Z`child_run_uuid`... |
| **status** | string | Current status of the run execution, e.g., "error", "pending", "success" |
| **child\_run\_ids** | array of UUIDs | List of IDs for all child runs. |
| **direct\_child\_run\_ids** | array of UUIDs | List of IDs for direct children of this run. |
| **parent\_run\_ids** | array of UUIDs | List of IDs for all parent runs. |
| **feedback\_stats** | object | Aggregations of feedback statistics for this run |
| **reference\_example\_id** | UUID | ID of a reference example associated with the run. This is usually only present for evaluation runs. |
| **total\_tokens** | integer | Total number of tokens processed by the run. |
| **prompt\_tokens** | integer | Number of tokens in the prompt of the run. |
| **completion\_tokens** | integer | Number of tokens in the completion of the run. |
| **total\_cost** | decimal | Total cost associated with processing the run. |
| **prompt\_cost** | decimal | Cost associated with the prompt part of the run. |
| **completion\_cost** | decimal | Cost associated with the completion of the run. |
| **first\_token\_time** | datetime | Time when the first token of a model output was generated. Only applies for runs with `run_type="llm"` and streaming enabled. |
| **session\_id** | string | Session identifier for the run, also known as the tracing project ID. |
| **in\_dataset** | boolean | Indicates whether the run is included in a dataset. |
| **parent\_run\_id** | UUID | Unique identifier of the parent run. |
| execution\_order (deprecated) | integer | The order in which this run was executed within the trace. |
| serialized | object | Serialized state of the object executing the run if applicable. |
| manifest\_id (deprecated) | UUID | Identifier for a manifest associated with the span. |
| manifest\_s3\_id | UUID | S3 identifier for the manifest. |
| inputs\_s3\_urls | object | S3 URLs for the inputs. |
| outputs\_s3\_urls | object | S3 URLs for the outputs. |
| price\_model\_id | UUID | Identifier for the pricing model applied to the run. |
| app\_path | string | Application (UI) path for this run. |
| last\_queued\_at | datetime | Last time the span was queued. |
| share\_token | string | Token for sharing access to the run's data. |
Here is an example of a JSON representation of a run in the above format:
```json theme={null}
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"inputs": {},
"run_type": "llm",
"start_time": "2024-04-29T00:49:12.090000",
"end_time": "2024-04-29T00:49:12.459000",
"extra": {},
"error": "string",
"execution_order": 1,
"serialized": {},
"outputs": {},
"parent_run_id": "f8faf8c1-9778-49a4-9004-628cdb0047e5",
"manifest_id": "82825e8e-31fc-47d5-83ce-cd926068341e",
"manifest_s3_id": "0454f93b-7eb6-4b9d-a203-f1261e686840",
"events": [{}],
"tags": ["foo"],
"inputs_s3_urls": {},
"outputs_s3_urls": {},
"trace_id": "df570c03-5a03-4cea-8df0-c162d05127ac",
"dotted_order": "20240429T004912090000Z497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "string",
"child_run_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
"direct_child_run_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
"parent_run_ids": ["f8faf8c1-9778-49a4-9004-628cdb0047e5"],
"feedback_stats": {
"correctness": {
"n": 1,
"avg": 1.0
}
},
"reference_example_id": "9fb06aaa-105f-4c87-845f-47d62ffd7ee6",
"total_tokens": 0,
"prompt_tokens": 0,
"completion_tokens": 0,
"total_cost": 0.0,
"prompt_cost": 0.0,
"completion_cost": 0.0,
"price_model_id": "0b5d9575-bec3-4256-b43a-05893b8b8440",
"first_token_time": null,
"session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
"app_path": "string",
"last_queued_at": null,
"in_dataset": true,
"share_token": "d0430ac3-04a1-4e32-a7ea-57776ad22c1c"
}
```
#### What is `dotted_order`?
A run's dotted order is a sortable key that fully specifies its location within the tracing hierarchy.
Take the following example:
```python theme={null}
import langsmith as ls
@ls.traceable
def grandchild():
p("grandchild")
@ls.traceable
def child():
grandchild()
@ls.traceable
def parent():
child()
```
If you print out the IDs at each stage, you may get the following:
```python theme={null}
parent run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7 trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7 parent_run_id=null dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7
child run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097 trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7 parent_run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7 dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097
grandchild run_id=0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6 trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7 parent_run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097 dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097.20240919T171648523563Z0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6
```
Note a few invariants:
* The "id" is equal to the last 36 characters of the dotted order (the suffix after the final "Z"). See `0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6` for example in the grandchild.
* The "trace\_id" is equal to the first UUID in the dotted order (i.e., `dotted_order.split('.')[0].split('Z')[1]`)
* If "parent\_run\_id" exists, it is the penultimate UUID in the dotted order. See `a8024e23-5b82-47fd-970e-f6a5ba3f5097` in the grandchild, for an example.
* If you split the dotted\_order on the dots, each segment is formatted as (`Z`)
***
[Edit the source of this page on GitHub.](https://github.com/langchain-ai/docs/edit/main/src/langsmith/run-data-format.mdx)
[Connect these docs programmatically](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.