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

# Logs abfragen

Durchsuchen Sie Log-Zeilen mit der [Public API (V2)](/api/v2/overview). Dies ist
der Weg, Logs programmatisch abzufragen, einschließlich strukturierter
(JSON-)Logdaten. Die GraphQL-API stellt keine Log-Zeilen bereit.

<Tip>
  Wenn Sie einen KI-Agenten oder Assistenten erstellen, stellt [AppSignal
  MCP](/mcp-server) die Logsuche und andere Monitoring-Daten direkt für Agenten
  bereit, ohne dass Sie diese API selbst aufrufen müssen.
</Tip>

## Site- und Quellen-IDs finden

Eine Logsuche benötigt eine `site_id` und eine oder mehrere `source_ids`. Beide
erscheinen in der URL einer Log-Quelle in AppSignal. Öffnen Sie eine Log-Quelle und
lesen Sie sie aus dem Pfad ab:

<CodeGroup>
  ```text URL theme={null}
  https://appsignal.com/<organization>/sites/<SITE_ID>/logs/sources/<SOURCE_ID>
  ```
</CodeGroup>

## Log-Zeilen durchsuchen

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/logs/lines
  ```
</CodeGroup>

### Request-Body

| Feld              | Typ               | Erforderlich | Beschreibung                                                                     |
| ----------------- | ----------------- | ------------ | -------------------------------------------------------------------------------- |
| `site_id`         | string            | Ja           | Abzufragende Site.                                                               |
| `source_ids`      | string\[]         | Ja           | Log-Quellen-IDs, die durchsucht werden sollen. Mindestens eine ist erforderlich. |
| `query`           | string            | Ja           | Abfragestring, der Log-Zeilen filtert. Siehe [Abfragesprache](#query-language).  |
| `use_expressions` | boolean           | Nein         | Wenn `true`, wird `query` mit der ausdrucksbasierten Abfragesprache geparst.     |
| `from`            | string (ISO 8601) | Nein         | Start des Zeitbereichs. Standardwert ist die untere Grenze der Aufbewahrung.     |
| `to`              | string (ISO 8601) | Nein         | Ende des Zeitbereichs. Standardwert ist die aktuelle Zeit.                       |
| `pagination`      | object            | Ja           | Paginierungs-Cursor und -Richtung (siehe folgenden Abschnitt).                   |

Setzen Sie `use_expressions` auf `true`, um die auf dieser Seite dokumentierte
ausdrucksbasierte Abfragesprache zu verwenden.

`pagination` nimmt `per_page` (Zahl), `order` (`ASC` oder `DESC`) und einen `cursor`
mit einem `time`-Feld (ein ISO-8601-Zeitstempel oder `null` für die erste Seite)
entgegen. Um die nächste Seite abzurufen, senden Sie den Zeitstempel der letzten
erhaltenen Zeile als `cursor.time` der nächsten Anfrage.

### Beispielanfrage

<CodeGroup>
  ```shell cURL theme={null}
  curl --request POST \
    --url "https://appsignal.com/api/v2/logs/lines" \
    --header "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
    --header "Content-Type: application/json" \
    --data @body.json
  ```
</CodeGroup>

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "source_ids": ["YOUR-LOG-SOURCE-ID"],
    "query": "severity=error status_code=401",
    "use_expressions": true,
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T23:59:59Z",
    "pagination": {
      "per_page": 100,
      "order": "DESC",
      "cursor": { "time": null }
    }
  }
  ```
</CodeGroup>

### Antwort

Der Endpunkt gibt ein Array von Log-Zeilen zurück. Jede Zeile enthält diese Felder:

| Feld         | Typ               | Beschreibung                                                                              |
| ------------ | ----------------- | ----------------------------------------------------------------------------------------- |
| `id`         | string            | Bezeichner der Log-Zeile.                                                                 |
| `timestamp`  | string (ISO 8601) | Zeitpunkt, zu dem die Log-Zeile aufgezeichnet wurde.                                      |
| `source_id`  | string            | Log-Quelle, zu der die Zeile gehört.                                                      |
| `severity`   | string            | Schweregrad, etwa `info` oder `error`.                                                    |
| `message`    | string            | Der Log-Nachrichtentext.                                                                  |
| `hostname`   | string            | Host, der die Zeile erzeugt hat.                                                          |
| `group`      | string            | Log-Gruppe.                                                                               |
| `json`       | string            | Der rohe strukturierte (JSON-)Body der Log-Zeile, sofern verfügbar.                       |
| `attributes` | object            | Veraltete typisierte Schlüssel-Wert-Attribute. Wird ausgemustert — bevorzugen Sie `json`. |

<Note>
  Strukturierte Felder wie `status_code`, `path` oder `detail` liegen im
  `json`-Feld, nicht in `attributes`. Fragen Sie sie über ihren exakten Schlüssel
  ab, wie er im JSON Ihres Logs erscheint (zum Beispiel `status_code=401` oder
  `detail.message:"required"`).
</Note>

## Abfragesprache

Wenn `use_expressions` `true` ist, unterstützt der `query`-String boolesche Logik
über Felder von Log-Zeilen und den strukturierten `json`-Body.

### Operatoren

| Operator | Name                | Verhalten                         |
| -------- | ------------------- | --------------------------------- |
| `=`      | Gleich              | Exakte Übereinstimmung.           |
| `!=`     | Ungleich            | Exakte Nicht-Übereinstimmung.     |
| `:`      | Enthält             | Teilstring-Übereinstimmung.       |
| `!:`     | Enthält nicht       | Teilstring-Nicht-Übereinstimmung. |
| `>`      | Größer als          | Numerischer Vergleich.            |
| `>=`     | Größer oder gleich  | Numerischer Vergleich.            |
| `<`      | Kleiner als         | Numerischer Vergleich.            |
| `<=`     | Kleiner oder gleich | Numerischer Vergleich.            |

String-Operatoren (`=`, `!=`, `:`, `!:`) vergleichen beide Seiten als Strings.
Numerische Operatoren (`>`, `>=`, `<`, `<=`) wandeln beide Seiten in eine Zahl um;
kann ein Wert nicht als Zahl geparst werden, wird diese Log-Zeile übersprungen.

### Ausdrücke kombinieren

* **AND / OR:** `severity=error AND hostname:web` oder `severity=info OR severity=warn`.
* **Implizites AND:** Ein Leerzeichen zwischen Ausdrücken bedeutet AND. `severity=error hostname:web` entspricht `severity=error AND hostname:web`.
* **Verschachtelung mit Klammern:** `message:"API request" AND (severity=info OR severity=warn)`.
* **Vorrang:** AND bindet stärker als OR.

Jeder Operator kann innerhalb einer `OR`-Gruppe verwendet werden, nicht nur
Gleichheit — zum Beispiel `message:"API request" AND (user.id>1000 OR user.email:"example.com")`.

### Felder

Gegeben sei eine Log-Zeile mit diesem JSON-Body:

<CodeGroup>
  ```json Example log theme={null}
  {
    "message": "API request completed",
    "severity": "info",
    "duration": 156.7,
    "status_code": 200,
    "user": {
      "id": 12345,
      "roles": ["admin", "developer"],
      "location.country": "US"
    }
  }
  ```
</CodeGroup>

* **Basisfelder:** `message`, `severity`, `hostname` und `group` passen auf die obersten Felder der Log-Zeile.
* **Verschachteltes JSON:** Verwenden Sie Punktnotation, um in den `json`-Body zu greifen, etwa `status_code=200` oder `user.id=12345`.
* **JSON-Arrays:** Indizieren Sie Array-Elemente, etwa `user.roles.0=admin`.
* **Escapte Punkte:** Um einen wörtlichen Punkt in einem Schlüsselnamen zu treffen, escapen Sie ihn. `user.location\.country=US` trifft den Schlüssel `location.country` innerhalb von `user`, statt eines verschachtelten `country`-Objekts.
* **Standardfeld:** Ein nackter Begriff ohne Feld trifft `message` mit dem `contains`-Operator. `timeout` entspricht `message:timeout`.

Sie müssen einem Feld kein `attributes.` voranstellen oder ein Typsuffix anhängen,
um es abzufragen — referenzieren Sie es direkt über den Namen. Siehe [alte
Abfragesyntax](#legacy-query-syntax), wenn Sie ältere Abfragen haben.

### Werte in Anführungszeichen

Setzen Sie Werte, die Leerzeichen oder Klammern enthalten, in doppelte
Anführungszeichen. Andernfalls trennt das Leerzeichen den Wert in separate
Ausdrücke, die durch implizites AND verbunden werden.

```text theme={null}
message:"hello world"           matches message containing "hello world"
message:hello world             parsed as message:hello AND message:world
severity=error message:"oh no"  severity equals error AND message contains "oh no"
```

Nur doppelte Anführungszeichen werden erkannt. Innerhalb eines zitierten Werts
escapen Sie ein Anführungszeichen mit `\"` und einen Backslash mit `\\`. Zum
Beispiel trifft `message:"value with \"quotes\""` den Text `value with "quotes"`.

### Alte Abfragesyntax

Ältere Abfragen speicherten Attribute als typisierte Felder, sodass sie
`attributes.` voranstellen, ein Typsuffix (`_string`, `_int`) anhängen und für
mehrere Werte eine `[ ]`-Liste verwenden mussten. Die aktuelle Abfragesprache
entfernt alle drei — referenzieren Sie Felder direkt und verwenden Sie `OR`
anstelle einer Liste:

<CodeGroup>
  ```text Old query theme={null}
  message:"API request" attributes.user_id_int=12345 severity=[info, warn]
  ```

  ```text New query theme={null}
  message:"API request" user.id=12345 (severity=info OR severity=warn)
  ```
</CodeGroup>

Eine Abfrage, die noch die alte Syntax verwendet, gibt einen `422` mit dem
Fehler-Slug `legacy_log_query_syntax` zurück.