Search function logs

POST

api

traces

logs

Search function logs

curl --request POST \
  --url https://api.example.com/api/v1/traces/logs/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "project_id": "<string>",
  "conversation_id": "<string>",
  "function_names": [
    "<string>"
  ],
  "levels": [
    "<string>"
  ],
  "client_envs": [
    "<string>"
  ],
  "error_types": [
    "<string>"
  ],
  "text": {},
  "trace_id": "<string>",
  "span_id": "<string>",
  "turn_index": 123,
  "from": {},
  "to": {},
  "order": "<string>",
  "limit": 123,
  "offset": 123
}
'

import requests

url = "https://api.example.com/api/v1/traces/logs/search"

payload = {
    "project_id": "<string>",
    "conversation_id": "<string>",
    "function_names": ["<string>"],
    "levels": ["<string>"],
    "client_envs": ["<string>"],
    "error_types": ["<string>"],
    "text": {},
    "trace_id": "<string>",
    "span_id": "<string>",
    "turn_index": 123,
    "from": {},
    "to": {},
    "order": "<string>",
    "limit": 123,
    "offset": 123
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project_id: '<string>',
    conversation_id: '<string>',
    function_names: ['<string>'],
    levels: ['<string>'],
    client_envs: ['<string>'],
    error_types: ['<string>'],
    text: {},
    trace_id: '<string>',
    span_id: '<string>',
    turn_index: 123,
    from: {},
    to: {},
    order: '<string>',
    limit: 123,
    offset: 123
  })
};

fetch('https://api.example.com/api/v1/traces/logs/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/traces/logs/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'project_id' => '<string>',
    'conversation_id' => '<string>',
    'function_names' => [
        '<string>'
    ],
    'levels' => [
        '<string>'
    ],
    'client_envs' => [
        '<string>'
    ],
    'error_types' => [
        '<string>'
    ],
    'text' => [
        
    ],
    'trace_id' => '<string>',
    'span_id' => '<string>',
    'turn_index' => 123,
    'from' => [
        
    ],
    'to' => [
        
    ],
    'order' => '<string>',
    'limit' => 123,
    'offset' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/traces/logs/search"

	payload := strings.NewReader("{\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"from\": {},\n  \"to\": {},\n  \"order\": \"<string>\",\n  \"limit\": 123,\n  \"offset\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/traces/logs/search")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"from\": {},\n  \"to\": {},\n  \"order\": \"<string>\",\n  \"limit\": 123,\n  \"offset\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/traces/logs/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"from\": {},\n  \"to\": {},\n  \"order\": \"<string>\",\n  \"limit\": 123,\n  \"offset\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "logs": [
    {
      "timestamp": {},
      "level": "<string>",
      "project_id": "<string>",
      "client_env": "<string>",
      "function_name": "<string>",
      "conversation_id": "<string>",
      "call_sid": "<string>",
      "event": "<string>",
      "error_type": "<string>",
      "trace_id": "<string>",
      "span_id": "<string>",
      "turn_index": "<string>"
    }
  ],
  "from": {},
  "to": {},
  "limit": 123,
  "offset": 123,
  "has_more": true
}

Returns the log lines written by the GenAI functions of an account, one entry per line, with the event label and the span the function ran in. Filter by conversation, function, level, environment, error type, whole-word text, or the exact span. The raw log line and its payload are never returned. See the overview for how lines link to spans.

Request

Headers

string

required

Account API key with read access to conversations.

Body

string

Restrict to one agent. Omit to search the whole account.

string

Matches the conversation ID or the call SID.

string[]

Function (tool) names, up to 20.

string[]

debug, info, warning, error, critical.

string[]

Environments: test, sandbox, pre-release, live, scenarios. pre-release is the Staging environment.

string[]

Exception classes on failure lines, for example KeyError, up to 20.

object

Whole-word, case-insensitive terms matched on the event label: { "all": [...], "any": [...], "none": [...] }, up to 10 terms each. api request finds API request error; api req does not.

string

Trace ID of the function-execution span.

string

Span ID of the function-execution span. Returns exactly the lines that one execution wrote.

integer

0-based turn the function call belongs to. Must be an integer.

datetime

Inclusive window start. Defaults to 24 hours before to. The window may span at most 30 days.

datetime

Exclusive window end. Defaults to now. The response echoes the value used; pass it back when paging so new lines do not shift the pages.

string

default:"desc"

desc (newest first) or asc.

integer

default:"50"

Lines per page, 1–100.

integer

default:"0"

Lines to skip, 0–1000.

Response

object[]

One entry per log line.

Show properties

datetime

string

The event label the function logged, for example API request error.

string

Exception class on a failure line, for example KeyError. Empty otherwise.

string

Trace ID of the function-execution span. Empty when the line is not linked.

string

Span ID of the function-execution span. Empty when the line is not linked.

string

0-based turn the call belongs to, as a string. Empty when unknown.

datetime

Window start actually used.

datetime

Window end actually used.

integer

boolean

Examples

Errors from one function in the last 24 hours

curl -X POST https://api.us.poly.ai/api/v1/traces/logs/search \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT-V258TF29",
    "function_names": ["send_sms"],
    "levels": ["error"],
    "limit": 2
  }'

{
  "logs": [
    {
      "timestamp": "2026-10-26T18:22:36.175000+00:00",
      "level": "error",
      "project_id": "PROJECT-V258TF29",
      "client_env": "live",
      "function_name": "send_sms",
      "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
      "call_sid": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
      "event": "SMS failed to send",
      "error_type": "",
      "trace_id": "183208fafb304cebf5e07c90f7b48f0f",
      "span_id": "8cff57c6d5aaa768",
      "turn_index": "10"
    }
  ],
  "from": "2026-10-26T13:57:43.353614+00:00",
  "to": "2026-10-27T13:57:43.353614+00:00",
  "limit": 2,
  "offset": 0,
  "has_more": true
}

Everything one execution wrote

Take span_id from a search result, or from a span search, and pass it back:

Request

{
  "project_id": "PROJECT-V258TF29",
  "span_id": "8cff57c6d5aaa768",
  "order": "asc"
}

Uncaught exceptions in a conversation

Request

{
  "project_id": "PROJECT-V258TF29",
  "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
  "error_types": ["KeyError", "TimeoutError"],
  "from": "2026-10-20T00:00:00Z",
  "to": "2026-10-27T00:00:00Z"
}

Errors

Status	Meaning
`400`	The window is empty or exceeds 30 days.
`401`	Missing or invalid API key.
`403`	The key cannot read conversations.
`422`	A value is outside its enum or range, or `turn_index` is not an integer.
`502`	The log backend did not answer.

Last modified on November 10, 2026

⌘I

Search function logs

curl --request POST \
  --url https://api.example.com/api/v1/traces/logs/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "project_id": "<string>",
  "conversation_id": "<string>",
  "function_names": [
    "<string>"
  ],
  "levels": [
    "<string>"
  ],
  "client_envs": [
    "<string>"
  ],
  "error_types": [
    "<string>"
  ],
  "text": {},
  "trace_id": "<string>",
  "span_id": "<string>",
  "turn_index": 123,
  "from": {},
  "to": {},
  "order": "<string>",
  "limit": 123,
  "offset": 123
}
'

import requests

url = "https://api.example.com/api/v1/traces/logs/search"

payload = {
    "project_id": "<string>",
    "conversation_id": "<string>",
    "function_names": ["<string>"],
    "levels": ["<string>"],
    "client_envs": ["<string>"],
    "error_types": ["<string>"],
    "text": {},
    "trace_id": "<string>",
    "span_id": "<string>",
    "turn_index": 123,
    "from": {},
    "to": {},
    "order": "<string>",
    "limit": 123,
    "offset": 123
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project_id: '<string>',
    conversation_id: '<string>',
    function_names: ['<string>'],
    levels: ['<string>'],
    client_envs: ['<string>'],
    error_types: ['<string>'],
    text: {},
    trace_id: '<string>',
    span_id: '<string>',
    turn_index: 123,
    from: {},
    to: {},
    order: '<string>',
    limit: 123,
    offset: 123
  })
};

fetch('https://api.example.com/api/v1/traces/logs/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/traces/logs/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'project_id' => '<string>',
    'conversation_id' => '<string>',
    'function_names' => [
        '<string>'
    ],
    'levels' => [
        '<string>'
    ],
    'client_envs' => [
        '<string>'
    ],
    'error_types' => [
        '<string>'
    ],
    'text' => [
        
    ],
    'trace_id' => '<string>',
    'span_id' => '<string>',
    'turn_index' => 123,
    'from' => [
        
    ],
    'to' => [
        
    ],
    'order' => '<string>',
    'limit' => 123,
    'offset' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/traces/logs/search"

	payload := strings.NewReader("{\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"from\": {},\n  \"to\": {},\n  \"order\": \"<string>\",\n  \"limit\": 123,\n  \"offset\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/traces/logs/search")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"from\": {},\n  \"to\": {},\n  \"order\": \"<string>\",\n  \"limit\": 123,\n  \"offset\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/traces/logs/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"from\": {},\n  \"to\": {},\n  \"order\": \"<string>\",\n  \"limit\": 123,\n  \"offset\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "logs": [
    {
      "timestamp": {},
      "level": "<string>",
      "project_id": "<string>",
      "client_env": "<string>",
      "function_name": "<string>",
      "conversation_id": "<string>",
      "call_sid": "<string>",
      "event": "<string>",
      "error_type": "<string>",
      "trace_id": "<string>",
      "span_id": "<string>",
      "turn_index": "<string>"
    }
  ],
  "from": {},
  "to": {},
  "limit": 123,
  "offset": 123,
  "has_more": true
}

API reference

Models

Build & deploy

Runtime & data

Monitoring

Legacy

Request

Headers

Body

Response

Examples

Errors from one function in the last 24 hours

Everything one execution wrote

Uncaught exceptions in a conversation

Errors

​Request

​Headers

​Body

​Response

​Examples

​Errors from one function in the last 24 hours

​Everything one execution wrote

​Uncaught exceptions in a conversation

​Errors

Request

Headers

Body

Response

Examples

Errors from one function in the last 24 hours

Everything one execution wrote

Uncaught exceptions in a conversation

Errors