Skip to main content
GET
https://app.artanis.ai
/
api
/
v1
/
traces
/
search
Search Traces
curl --request GET \
  --url https://app.artanis.ai/api/v1/traces/search \
  --header 'Authorization: Bearer <token>'
{
  "traces": [
    {}
  ],
  "count": 123
}

​
Overview

The /api/v1/traces/search endpoint allows you to find traces using identifiers stored in trace metadata. This is useful when you need to:
  • Look up a trace ID from your internal identifiers (group IDs, ticket IDs, etc.)
  • Find the trace ID before submitting feedback
  • Verify that a trace exists for a given context
Traces store custom metadata that you provide when creating them. This endpoint searches those metadata fields to help you find the corresponding trace ID.

​
Query Parameters

​
group_id
string
Find traces by group ID (e.g., conversation ID, session ID).
​
name
string
Find traces by name.
​
status
string
Find traces by status (running or completed).
​
limit
number
default:"10"
Maximum number of results to return (max 100).
You can also search by any metadata field stored on your traces (e.g., ?criterion_id=...). All provided fields must match (AND logic).

​
Response

​
traces
array
Array of matching traces. Each trace contains:
  • trace_id — The trace identifier (use this for feedback submission)
  • name — The trace name
  • status — Current status (running or completed)
  • metadata — Full metadata object
  • timestamp — When the trace was created
​
count
number
Number of traces returned.

​
Examples

Find traces by a metadata field: 
const response = await fetch(
  "https://app.artanis.ai/api/v1/traces/search?group_id=group_abc123",
  {
    headers: {
      Authorization: "Bearer ak_...",
    },
  }
);

const data = await response.json();
if (data.count > 0) {
  const traceId = data.traces[0].trace_id;
  console.log(`Found trace: ${traceId}`);
}
Response: 
{
  "traces": [
    {
      "trace_id": "trace_abc123xyz789",
      "name": "Customer support evaluation",
      "status": "completed",
      "metadata": {
        "group_id": "group_abc123",
        "ticket_id": "SUPPORT-456"
      },
      "timestamp": "2025-12-22T10:30:00.000Z"
    }
  ],
  "count": 1
}
Find a specific trace by combining multiple metadata fields: 
const params = new URLSearchParams({
  group_id: "group_abc123",
  criterion_id: "criterion_xyz789",
});

const response = await fetch(
  `https://app.artanis.ai/api/v1/traces/search?${params}`,
  {
    headers: {
      Authorization: "Bearer ak_...",
    },
  }
);

​
Complete Workflow: Search + Feedback

A common pattern is to search for a trace, then submit feedback: 
const API_KEY = "ak_...";
const BASE_URL = "https://app.artanis.ai";

// Step 1: Find the trace by your internal identifiers
const params = new URLSearchParams({
  group_id: "group_abc123",
  criterion_id: "criterion_xyz789",
});

const searchResponse = await fetch(`${BASE_URL}/api/v1/traces/search?${params}`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});

const searchData = await searchResponse.json();
if (searchData.count === 0) {
  throw new Error("No trace found");
}

const traceId = searchData.traces[0].trace_id;

// Step 2: Submit feedback
const feedbackResponse = await fetch(`${BASE_URL}/api/v1/feedback`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    trace_id: traceId,
    rating: 0.8,
    comment: "Good evaluation, minor issues",
    timestamp: new Date().toISOString(),
  }),
});

console.log(`Feedback submitted for trace ${traceId}`);

​
Error Responses

Status CodeErrorSolution
400At least one search parameter is requiredProvide metadata fields as query parameters
401Invalid API keyVerify your API key is correct
429Rate limit exceededImplement exponential backoff retry

​
Next Steps

Submit Feedback

Submit feedback using the trace ID you found

Create Traces

Learn how to create traces with metadata