> ## 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.

# Search log lines

For the query language and how to find your source IDs, see [Querying logs](https://docs.appsignal.com/api/v2/logs.md).

```yaml POST /api/v2/logs/lines theme={null}
openapi: 3.1.0
info:
  title: AppSignal V2 API
  description: >-
    REST API for metrics, traces, logs, Kubernetes monitoring, and deployment
    tracking.
  license:
    name: ''
  version: 0.1.0
paths:
  /api/v2/logs/lines:
    post:
      tags:
        - Logs
      summary: Search log lines
      operationId: lines
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogsQueryParams'
            example:
              site_id: abc123
              from: '2024-01-01T00:00:00Z'
              to: '2024-01-01T01:00:00Z'
              source_ids:
                - source-1
                - source-2
              query: error
              pagination:
                per_page: 50
                order: DESC
                cursor:
                  time: null
                  id: null
        required: true
      responses:
        '200':
          description: >-
            The matching log lines, or a server-sent event stream whose `data`
            fields are each a `LogStreamEvent`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogLine'
            text/event-stream:
              schema:
                type: string
        '400':
          description: Malformed request, or input the server cannot process.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Missing or invalid authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Route or resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: External query concurrency limit exceeded; retry shortly.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
        '500':
          description: Unhandled server-side failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer_auth: []
        - token_query: []
components:
  schemas:
    BadRequestResponse:
      type: object
      description: >-
        Standard body for HTTP 400 Bad Request responses. Branch on the stable
        `error` slug, display `message` as-is, and read per-error structured
        data from `details`.
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Stable, machine-readable slug identifying the specific error case.
        message:
          type: string
          description: Human-readable message. Safe to log or display to end users.
        details:
          description: >-
            Per-error structured payload. Shape varies by
            [`error`](Self::error).
    ErrorResponse:
      type: object
      description: Error body returned for 401, 404 and 500 responses.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
    LogLine:
      type: object
      description: A log line; its attributes live inside `json`.
      required:
        - timestamp
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the line was logged, with millisecond precision.
        id:
          type:
            - string
            - 'null'
          description: Unique ID of the line.
        source_id:
          type:
            - string
            - 'null'
          description: Log source the line was ingested through.
        group:
          type:
            - string
            - 'null'
          description: Group the line belongs to, such as the app or service name.
        severity:
          type:
            - string
            - 'null'
          description: Severity level, such as `info` or `error`.
        message:
          type:
            - string
            - 'null'
          description: The log message.
        hostname:
          type:
            - string
            - 'null'
          description: Host that emitted the line.
        json:
          type:
            - string
            - 'null'
          description: The line's attributes as a JSON-encoded string.
    LogStreamEvent:
      oneOf:
        - type: object
          description: Query statistics, sent after every searched time chunk.
          required:
            - data
            - type
          properties:
            data:
              $ref: '#/components/schemas/QueryProgress'
              description: Query statistics, sent after every searched time chunk.
            type:
              type: string
              enum:
                - Progress
        - type: object
          description: Log lines found in the last searched time chunk.
          required:
            - data
            - type
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/LogLine'
              description: Log lines found in the last searched time chunk.
            type:
              type: string
              enum:
                - Data
        - type: object
          description: The search finished; always the last event.
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - Complete
        - type: object
          description: The search failed; followed by `Complete`.
          required:
            - data
            - type
          properties:
            data:
              type: string
              description: The search failed; followed by `Complete`.
            type:
              type: string
              enum:
                - error
      description: >-
        One server-sent event of a streamed log search, as the JSON `data` of
        the event.
    LogsQueryParams:
      type: object
      description: Filters and pagination for searching log lines.
      required:
        - site_id
        - source_ids
        - query
        - pagination
      properties:
        site_id:
          type: string
          description: Site to search; an empty value returns no log lines.
        from:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Start of the time range; defaults to the start of the account's log
            retention and is clamped to it and now.
        to:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            End of the time range; defaults to now and is clamped to
            `from`..now.
        source_ids:
          type: array
          items:
            type: string
          description: Log sources to search; an empty list returns no log lines.
        query:
          type: string
          description: Log search query; an empty string matches every line.
        pagination:
          $ref: '#/components/schemas/Pagination_LogPagination'
          description: Page size, order and cursor.
    Order:
      type: string
      description: |-
        Sort order for query results

        Used across multiple domains for paginated and ordered queries.
      enum:
        - ASC
        - DESC
    Pagination_LogPagination:
      type: object
      description: Keyset pagination settings, generic over each domain's cursor type.
      required:
        - per_page
        - order
        - cursor
      properties:
        per_page:
          type: integer
          format: int32
          description: Number of results per page.
          minimum: 1
        order:
          $ref: '#/components/schemas/Order'
          description: Sort order for results.
        cursor:
          type: object
          description: Pagination cursor for log lines.
          properties:
            time:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                Timestamp of the last line on the previous page; `null` starts
                from the first page.
            id:
              type:
                - string
                - 'null'
              description: >-
                ID of the last line on the previous page; without it, lines
                sharing `time` are skipped.
    QueryProgress:
      type: object
      description: Progress of a log search, which runs over the time range in chunks.
      required:
        - rows_read
        - bytes_read
        - total_rows_to_read
        - progress_percentage
        - processed_chunks
        - total_chunks
        - rows_returned
      properties:
        rows_read:
          type: integer
          format: u-int64
          description: Number of rows read so far across all chunks.
          minimum: 0
        bytes_read:
          type: integer
          format: u-int64
          description: Number of bytes read so far across all chunks.
          minimum: 0
        total_rows_to_read:
          type: integer
          format: u-int64
          description: Estimated total rows to read across all chunks.
          minimum: 0
        progress_percentage:
          type: number
          format: double
          description: Overall progress as a percentage (0.0–100.0).
        processed_chunks:
          type: integer
          format: u-int64
          description: Number of time chunks processed so far.
          minimum: 0
        total_chunks:
          type: integer
          format: u-int64
          description: Total number of time chunks to process.
          minimum: 0
        rows_returned:
          type: integer
          format: u-int64
          description: Number of rows included in the response so far.
          minimum: 0
    TooManyRequestsResponse:
      type: object
      description: Error body returned for 429 responses.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        suggestion:
          type:
            - string
            - 'null'
          description: >-
            A cheaper way to write the request's filter. Only the trace list

            endpoints set it, and only for a filter with a known indexed
            rewrite.
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <token>`'
    token_query:
      type: apiKey
      in: query
      name: token
      description: >-
        Alternative to the Authorization header: pass the token as a
        `?token=<token>` query parameter.
```


## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.appsignal.com/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.