> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs

> Search log records and navigate from a log entry to its parent trace.

AgentVista stores structured log records ingested via the OTLP endpoint. The dashboard API lets you search logs with full-text and field-level filters, and follow a log entry directly to its parent trace.

<Note>
  To ingest log data, use the [OTLP ingestion endpoint](/api/otlp). The endpoints on this page are read-only dashboard endpoints.
</Note>

***

## Search logs

<CodeGroup>
  ```bash Full-text search theme={null}
  curl "https://api.agentvista.dev/api/v1/dashboard/logs/search?q=connection+refused&severity=error&limit=50" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```bash Filter by service and time range theme={null}
  curl "https://api.agentvista.dev/api/v1/dashboard/logs/search?service_name=api-gateway&start=2024-01-15T00:00:00Z&end=2024-01-15T23:59:59Z" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```bash Filter by trace theme={null}
  curl "https://api.agentvista.dev/api/v1/dashboard/logs/search?trace_id=550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /dashboard/logs/search`

Searches log records for the authenticated user using full-text search on the log body and exact-match filters on structured fields. Results are ordered newest-first.

### Query parameters

<ParamField query="q" type="string">
  Full-text search query run against the log body field using PostgreSQL full-text search.
</ParamField>

<ParamField query="service_name" type="string">
  Exact match filter on the `service_name` field.
</ParamField>

<ParamField query="severity" type="string">
  Exact match filter on severity level. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
</ParamField>

<ParamField query="trace_id" type="string">
  Filter logs linked to a specific trace UUID. Returns only logs emitted during that trace.
</ParamField>

<ParamField query="start" type="string">
  ISO 8601 datetime. Only logs at or after this time are returned.
</ParamField>

<ParamField query="end" type="string">
  ISO 8601 datetime. Only logs at or before this time are returned.
</ParamField>

<ParamField query="limit" type="number" default="100">
  Maximum number of records to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset. Use with `limit` to page through results.
</ParamField>

### Response — 200

<ResponseField name="total" type="number">
  Total number of matching log records (before pagination).
</ResponseField>

<ResponseField name="logs" type="object[]">
  Matching log records for the current page, ordered newest-first.

  <Expandable title="log record fields">
    <ResponseField name="id" type="string">
      UUID of the log record.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp when the log was emitted.
    </ResponseField>

    <ResponseField name="severity" type="string">
      Severity level: `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.
    </ResponseField>

    <ResponseField name="service_name" type="string">
      Name of the service that emitted this log (from the OTLP `service.name` resource attribute).
    </ResponseField>

    <ResponseField name="body" type="string">
      The log message body.
    </ResponseField>

    <ResponseField name="attributes" type="object">
      Key-value attributes attached to this log record.
    </ResponseField>

    <ResponseField name="trace_id" type="string | null">
      UUID of the trace this log was emitted during, or `null` if the log has no trace context.
    </ResponseField>

    <ResponseField name="span_id" type="string | null">
      UUID of the span this log was emitted during, or `null`.
    </ResponseField>

    <ResponseField name="trace_url" type="string | null">
      Computed navigation URL for the linked trace: `/traces/{trace_id}`. `null` when `trace_id` is null.
    </ResponseField>
  </Expandable>
</ResponseField>

```json Example response theme={null}
{
  "total": 1523,
  "logs": [
    {
      "id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
      "timestamp": "2024-01-15T12:05:23.441Z",
      "severity": "error",
      "service_name": "api-gateway",
      "body": "connection refused: upstream timeout after 30s",
      "attributes": {
        "http.method": "POST",
        "http.url": "https://internal-service/classify"
      },
      "trace_id": "550e8400-e29b-41d4-a716-446655440000",
      "span_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "trace_url": "/traces/550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
```

***

## Get trace link for a log

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/dashboard/logs/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/trace \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /dashboard/logs/{log_id}/trace`

Returns trace navigation data for a specific log record. Use this to jump from a log entry to the full trace waterfall. Returns `404` if the log record does not exist, does not belong to the authenticated user, or has no `trace_id`.

### Path parameters

<ParamField path="log_id" type="string" required>
  UUID of the log record.
</ParamField>

### Response — 200

<ResponseField name="trace_id" type="string">
  UUID of the trace this log was emitted during.
</ResponseField>

<ResponseField name="trace_url" type="string">
  Navigation URL for the trace: `/traces/{trace_id}`.
</ResponseField>

```json theme={null}
{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_url": "/traces/550e8400-e29b-41d4-a716-446655440000"
}
```