Skip to content

Commit 15e6c5d

Browse files
nirganirga
authored
docs: warehouse api docs (#120)
1 parent 3e37f3a commit 15e6c5d

File tree

2 files changed

+242
-5
lines changed

2 files changed

+242
-5
lines changed

‎api-reference/warehouse/get_spans.mdx‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
title: "Get Spans"
3+
api: "GET https://app.traceloop.com/api/v2/warehouse/spans"
4+
---
5+
6+
Retrieve spans from the data warehouse with flexible filtering and pagination options. This endpoint allows you to query trace data based on various criteria including time ranges, environments, workflows, attributes, and more.
7+
8+
## Request Parameters
9+
10+
<ParamField query="env" type="string">
11+
The environment name.
12+
</ParamField>
13+
14+
<ParamField query="environments" type="string[]">
15+
List of environment names to filter by.
16+
</ParamField>
17+
18+
<ParamField query="envProjectIDs" type="string[]">
19+
List of environment project IDs to filter by.
20+
</ParamField>
21+
22+
<ParamField query="fromTimestampSec" type="int64" required>
23+
Start time in Unix seconds timestamp.
24+
</ParamField>
25+
26+
<ParamField query="toTimestampSec" type="int64" required>
27+
End time in Unix seconds timestamp.
28+
</ParamField>
29+
30+
<ParamField query="workflowName" type="string">
31+
Filter spans by workflow name.
32+
</ParamField>
33+
34+
<ParamField query="attributes" type="map[string]string">
35+
Key-value pairs of attributes to filter by.
36+
</ParamField>
37+
38+
<ParamField query="spanName" type="string">
39+
Filter spans by span name.
40+
</ParamField>
41+
42+
<ParamField query="sortOrder" type="string">
43+
Sort order for results. Accepted values: `asc` or `desc`.
44+
</ParamField>
45+
46+
<ParamField query="sortBy" type="string">
47+
Field to sort by (e.g., `timestamp`, `duration`).
48+
</ParamField>
49+
50+
<ParamField query="cursor" type="int64">
51+
**Deprecated:** Use `compositeCursor` instead. Pagination cursor for fetching
52+
the next set of results.
53+
</ParamField>
54+
55+
<ParamField query="compositeCursor" type="CompositeCursor">
56+
Advanced pagination cursor for fetching the next set of results.
57+
</ParamField>
58+
59+
<ParamField query="limit" type="int">
60+
Maximum number of spans to return.
61+
</ParamField>
62+
63+
<ParamField query="filters" type="FilterCondition[]">
64+
Array of filter conditions to apply to the query.
65+
</ParamField>
66+
67+
<ParamField query="logicalOperator" type="string">
68+
Logical operator to apply between filter conditions. Accepted values: `AND` or
69+
`OR`.
70+
</ParamField>
71+
72+
## Response
73+
74+
Returns an array of Span objects:
75+
76+
<ResponseField name="organizationId" type="string">
77+
The organization ID associated with the span.
78+
</ResponseField>
79+
80+
<ResponseField name="environment" type="string">
81+
The environment where the span was captured.
82+
</ResponseField>
83+
84+
<ResponseField name="timestamp" type="timestamp">
85+
The timestamp when the span was created.
86+
</ResponseField>
87+
88+
<ResponseField name="traceId" type="string">
89+
The unique trace identifier.
90+
</ResponseField>
91+
92+
<ResponseField name="spanId" type="string">
93+
The unique span identifier.
94+
</ResponseField>
95+
96+
<ResponseField name="parentSpanId" type="string">
97+
The parent span identifier.
98+
</ResponseField>
99+
100+
<ResponseField name="traceState" type="string">
101+
The trace state information.
102+
</ResponseField>
103+
104+
<ResponseField name="spanName" type="string">
105+
The name of the span.
106+
</ResponseField>
107+
108+
<ResponseField name="spanKind" type="string">
109+
The kind of span (e.g., CLIENT, SERVER, INTERNAL).
110+
</ResponseField>
111+
112+
<ResponseField name="serviceName" type="string">
113+
The name of the service that generated the span.
114+
</ResponseField>
115+
116+
<ResponseField name="resourceAttributes" type="map">
117+
Key-value pairs of resource attributes.
118+
</ResponseField>
119+
120+
<ResponseField name="scopeName" type="string">
121+
The instrumentation scope name.
122+
</ResponseField>
123+
124+
<ResponseField name="scopeVersion" type="string">
125+
The instrumentation scope version.
126+
</ResponseField>
127+
128+
<ResponseField name="spanAttributes" type="map">
129+
Key-value pairs of span attributes.
130+
</ResponseField>
131+
132+
<ResponseField name="workflowName" type="string">
133+
The workflow name associated with the span.
134+
</ResponseField>
135+
136+
<ResponseField name="duration" type="int64">
137+
The duration of the span in nanoseconds.
138+
</ResponseField>
139+
140+
<ResponseField name="statusCode" type="string">
141+
The status code of the span (e.g., OK, ERROR).
142+
</ResponseField>
143+
144+
<ResponseField name="statusMessage" type="string">
145+
The status message providing additional context.
146+
</ResponseField>
147+
148+
<ResponseField name="eventsName" type="string[]">
149+
Array of event names associated with the span.
150+
</ResponseField>
151+
152+
<ResponseField name="eventsAttributes" type="map[]">
153+
Array of event attributes as key-value pairs.
154+
</ResponseField>
155+
156+
<ResponseField name="prompts" type="map">
157+
Prompt data associated with the span.
158+
</ResponseField>
159+
160+
<ResponseField name="completions" type="map">
161+
Completion data associated with the span.
162+
</ResponseField>
163+
164+
<ResponseField name="input" type="string">
165+
Input data for the span.
166+
</ResponseField>
167+
168+
<ResponseField name="output" type="string">
169+
Output data for the span.
170+
</ResponseField>
171+
172+
## Example Response
173+
174+
```json
175+
[
176+
{
177+
"organizationId": "org_123",
178+
"environment": "production",
179+
"timestamp": "2025-11-01T12:00:00Z",
180+
"traceId": "trace_abc123",
181+
"spanId": "span_def456",
182+
"parentSpanId": "span_parent_789",
183+
"traceState": "",
184+
"spanName": "llm.completion",
185+
"spanKind": "CLIENT",
186+
"serviceName": "chat-service",
187+
"resourceAttributes": {
188+
"service.version": "1.0.0"
189+
},
190+
"scopeName": "opentelemetry",
191+
"scopeVersion": "1.0.0",
192+
"spanAttributes": {
193+
"llm.model": "gpt-4",
194+
"llm.provider": "openai"
195+
},
196+
"workflowName": "chat-workflow",
197+
"duration": 1500000000,
198+
"statusCode": "OK",
199+
"statusMessage": "",
200+
"eventsName": ["start", "end"],
201+
"eventsAttributes": [
202+
{
203+
"event.type": "start"
204+
},
205+
{
206+
"event.type": "end"
207+
}
208+
],
209+
"prompts": {
210+
"role": "user",
211+
"content": "Hello, how are you?"
212+
},
213+
"completions": {
214+
"role": "assistant",
215+
"content": "I'm doing well, thank you!"
216+
},
217+
"input": "Hello, how are you?",
218+
"output": "I'm doing well, thank you!"
219+
}
220+
]
221+
```

‎mint.json‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,9 @@
149149
"pages": ["datasets/quick-start", "datasets/sdk-usage"]
150150
},
151151
{
152-
"group": "Playgrounds",
152+
"group": "Playgrounds",
153153
"pages": [
154-
"playgrounds/quick-start",
154+
"playgrounds/quick-start",
155155
{
156156
"group": "Columns",
157157
"pages": [
@@ -164,15 +164,27 @@
164164
},
165165
{
166166
"group": "Evaluators",
167-
"pages": ["evaluators/intro", "evaluators/custom-evaluator", "evaluators/made-by-traceloop"]
167+
"pages": [
168+
"evaluators/intro",
169+
"evaluators/custom-evaluator",
170+
"evaluators/made-by-traceloop"
171+
]
168172
},
169173
{
170174
"group": "Experiments",
171-
"pages": ["experiments/introduction", "experiments/result-overview", "experiments/running-from-code"]
175+
"pages": [
176+
"experiments/introduction",
177+
"experiments/result-overview",
178+
"experiments/running-from-code"
179+
]
172180
},
173181
{
174182
"group": "Monitoring",
175-
"pages": ["monitoring/introduction", "monitoring/defining-monitors", "monitoring/using-monitors"]
183+
"pages": [
184+
"monitoring/introduction",
185+
"monitoring/defining-monitors",
186+
"monitoring/using-monitors"
187+
]
176188
},
177189
{
178190
"group": "Prompt Management",
@@ -219,6 +231,10 @@
219231
{
220232
"group": "Costs",
221233
"pages": ["api-reference/costs/property_costs"]
234+
},
235+
{
236+
"group": "Warehouse",
237+
"pages": ["api-reference/warehouse/get_spans"]
222238
}
223239
],
224240
"redirects": [

0 commit comments

Comments
 (0)