# Spans ## Create Span `spans.create(SpanCreateParams**kwargs) -> Span` **post** `/spans` Create a new span with the provided parameters ### Parameters - `name: str` Name that describes what operation this span represents - `start_time: Union[str, datetime]` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `id: Optional[str]` Unique identifier for the span. If not provided, an ID will be generated. - `data: Optional[Union[Dict[str, object], Iterable[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `Iterable[Dict[str, object]]` - `end_time: Optional[Union[str, datetime, null]]` The time the span ended - `input: Optional[Union[Dict[str, object], Iterable[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `Iterable[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], Iterable[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `Iterable[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to ### Returns - `class Span: …` - `id: str` - `name: str` Name that describes what operation this span represents - `start_time: datetime` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `data: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `List[Dict[str, object]]` - `end_time: Optional[datetime]` The time the span ended - `input: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to ### Example ```python import os from datetime import datetime from agentex import Agentex client = Agentex( api_key=os.environ.get("AGENTEX_SDK_API_KEY"), # This is the default and can be omitted ) span = client.spans.create( name="name", start_time=datetime.fromisoformat("2019-12-27T18:11:19.117"), trace_id="trace_id", ) print(span.id) ``` #### Response ```json { "id": "id", "name": "name", "start_time": "2019-12-27T18:11:19.117Z", "trace_id": "trace_id", "data": { "foo": "bar" }, "end_time": "2019-12-27T18:11:19.117Z", "input": { "foo": "bar" }, "output": { "foo": "bar" }, "parent_id": "parent_id", "task_id": "task_id" } ``` ## List Spans `spans.list(SpanListParams**kwargs) -> SpanListResponse` **get** `/spans` List spans, optionally filtered by trace_id and/or task_id ### Parameters - `limit: Optional[int]` - `order_by: Optional[str]` - `order_direction: Optional[str]` - `page_number: Optional[int]` - `task_id: Optional[str]` - `trace_id: Optional[str]` ### Returns - `List[Span]` - `id: str` - `name: str` Name that describes what operation this span represents - `start_time: datetime` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `data: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `List[Dict[str, object]]` - `end_time: Optional[datetime]` The time the span ended - `input: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to ### Example ```python import os from agentex import Agentex client = Agentex( api_key=os.environ.get("AGENTEX_SDK_API_KEY"), # This is the default and can be omitted ) spans = client.spans.list() print(spans) ``` #### Response ```json [ { "id": "id", "name": "name", "start_time": "2019-12-27T18:11:19.117Z", "trace_id": "trace_id", "data": { "foo": "bar" }, "end_time": "2019-12-27T18:11:19.117Z", "input": { "foo": "bar" }, "output": { "foo": "bar" }, "parent_id": "parent_id", "task_id": "task_id" } ] ``` ## Partial Update Span `spans.update(strspan_id, SpanUpdateParams**kwargs) -> Span` **patch** `/spans/{span_id}` Update a span with the provided output data and mark it as complete ### Parameters - `span_id: str` - `data: Optional[Union[Dict[str, object], Iterable[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `Iterable[Dict[str, object]]` - `end_time: Optional[Union[str, datetime, null]]` The time the span ended - `input: Optional[Union[Dict[str, object], Iterable[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `Iterable[Dict[str, object]]` - `name: Optional[str]` Name that describes what operation this span represents - `output: Optional[Union[Dict[str, object], Iterable[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `Iterable[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `start_time: Optional[Union[str, datetime, null]]` The time the span started - `task_id: Optional[str]` ID of the task this span belongs to - `trace_id: Optional[str]` Unique identifier for the trace this span belongs to ### Returns - `class Span: …` - `id: str` - `name: str` Name that describes what operation this span represents - `start_time: datetime` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `data: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `List[Dict[str, object]]` - `end_time: Optional[datetime]` The time the span ended - `input: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to ### Example ```python import os from agentex import Agentex client = Agentex( api_key=os.environ.get("AGENTEX_SDK_API_KEY"), # This is the default and can be omitted ) span = client.spans.update( span_id="span_id", ) print(span.id) ``` #### Response ```json { "id": "id", "name": "name", "start_time": "2019-12-27T18:11:19.117Z", "trace_id": "trace_id", "data": { "foo": "bar" }, "end_time": "2019-12-27T18:11:19.117Z", "input": { "foo": "bar" }, "output": { "foo": "bar" }, "parent_id": "parent_id", "task_id": "task_id" } ``` ## Get Span `spans.retrieve(strspan_id) -> Span` **get** `/spans/{span_id}` Get a span by ID ### Parameters - `span_id: str` ### Returns - `class Span: …` - `id: str` - `name: str` Name that describes what operation this span represents - `start_time: datetime` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `data: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `List[Dict[str, object]]` - `end_time: Optional[datetime]` The time the span ended - `input: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to ### Example ```python import os from agentex import Agentex client = Agentex( api_key=os.environ.get("AGENTEX_SDK_API_KEY"), # This is the default and can be omitted ) span = client.spans.retrieve( "span_id", ) print(span.id) ``` #### Response ```json { "id": "id", "name": "name", "start_time": "2019-12-27T18:11:19.117Z", "trace_id": "trace_id", "data": { "foo": "bar" }, "end_time": "2019-12-27T18:11:19.117Z", "input": { "foo": "bar" }, "output": { "foo": "bar" }, "parent_id": "parent_id", "task_id": "task_id" } ``` ## Domain Types ### Span - `class Span: …` - `id: str` - `name: str` Name that describes what operation this span represents - `start_time: datetime` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `data: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `List[Dict[str, object]]` - `end_time: Optional[datetime]` The time the span ended - `input: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to ### Span List Response - `List[Span]` - `id: str` - `name: str` Name that describes what operation this span represents - `start_time: datetime` The time the span started - `trace_id: str` Unique identifier for the trace this span belongs to - `data: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Any additional metadata or context for the span - `Dict[str, object]` - `List[Dict[str, object]]` - `end_time: Optional[datetime]` The time the span ended - `input: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Input parameters or data for the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `output: Optional[Union[Dict[str, object], List[Dict[str, object]], null]]` Output data resulting from the operation - `Dict[str, object]` - `List[Dict[str, object]]` - `parent_id: Optional[str]` ID of the parent span if this is a child span in a trace - `task_id: Optional[str]` ID of the task this span belongs to