Matrix: a table of values where each row represents a different label setand the columns are each sample value for that row over the queried time.Matrix types are only returned when running a query that computes some value.
Instant Vector: denoted in the type as just vector, an Instant Vectorrepresents the latest value of a calculation for a given labelset. InstantVectors are only returned when doing a query against a single point intime.
Stream: a Stream is a set of all values (logs) for a given label set over thequeried time range. Streams are the only type that will result in log linesbeing returned.

`GET /loki/api/v1/query`

/loki/api/v1/query allows for doing queries against a single point in time. The URLquery parameters support the following values:

query: The LogQL query to perform
limit: The max number of entries to return
time: The evaluation time for the query as a nanosecond Unix epoch. Defaults to now.
direction: Determines the sort order of logs. Supported values are forward or backward. Defaults to backward.

In microservices mode, /loki/api/v1/query is exposed by the querier.

Response:

{
  "status": "success",
  "data": {
    "resultType": "vector" | "streams",
    "result": [<vector value>] | [<stream value>]
  }
}

Where <vector value> is:

{
  "metric": {
    <label key-value pairs>
  },
  "value": [
    <number: nanosecond unix epoch>,
    <string: value>
  ]
}

And <stream value> is:

{
  "stream": {
    <label key-value pairs>
  },
  "values": [
    [
      <string: nanosecond unix epoch>,
      <string: log line>
    ],
    ...
  ]
}

Examples

$ curl -G -s  "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {},
        "value": [
          1559848867745737,
          "1267.1266666666666"
        ]
      },
      {
        "metric": {
          "level": "warn"
        },
        "value": [
          1559848867745737,
          "37.77166666666667"
        ]
      },
      {
        "metric": {
          "level": "info"
        },
        "value": [
          1559848867745737,
          "37.69"
        ]
      }
    ]
  }
}

$ curl -G -s  "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query={job="varlogs"}' | jq
{
  "status": "success",
  "data": {
    "resultType": "streams",
    "result": [
      {
        "stream": {
          "filename": "/var/log/myproject.log",
          "job": "varlogs",
          "level": "info"
        },
        "values": [
          [
            "1568234281726420425",
            "foo"
          ],
          [
            "1568234269716526880",
            "bar"
          ]
        ]
      }
    ]
  }
}

`GET /loki/api/v1/query_range`

/loki/api/v1/query_range is used to do a query over a range of time andaccepts the following query parameters in the URL:

query: The LogQL query to perform
limit: The max number of entries to return
start: The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago.
end: The start time for the query as a nanosecond Unix epoch. Defaults to now.
step: Query resolution step width in seconds. Defaults to a dynamic value based on start and end.
direction: Determines the sort order of logs. Supported values are forward or backward. Defaults to backward.

Requests against this endpoint require Loki to query the index store in order tofind log streams for particular labels. Because the index store is spread out bytime, the time span covered by start and end, if large, may cause additionalload against the index server and result in a slow query.

In microservices mode, /loki/api/v1/query_range is exposed by the querier.

Response:

{
  "status": "success",
  "data": {
    "resultType": "matrix" | "streams",
    "result": [<matrix value>] | [<stream value>]
  }
}

Where <matrix value> is:

{
  "metric": {
    <label key-value pairs>
  },
  "values": [
    <number: nanosecond unix epoch>,
    <string: value>
  ]
}

And <stream value> is:

{
  "stream": {
    <label key-value pairs>
  },
  "values": [
    [
      <string: nanosecond unix epoch>,
      <string: log line>
    ],
    ...
  ]
}

Examples

$ curl -G -s  "http://localhost:3100/loki/api/v1/query_range" --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' --data-urlencode 'step=300' | jq
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
       "metric": {
          "level": "info"
        },
        "values": [
          [
            1559848958663735,
            "137.95"
          ],
          [
            1559849258663735,
            "467.115"
          ],
          [
            1559849558663735,
            "658.8516666666667"
          ]
        ]
      },
      {
        "metric": {
          "level": "warn"
        },
        "values": [
          [
            1559848958663735,
            "137.27833333333334"
          ],
          [
            1559849258663735,
            "467.69"
          ],
          [
            1559849558663735,
            "660.6933333333334"
          ]
        ]
      }
    ]
  }
}

$ curl -G -s  "http://localhost:3100/loki/api/v1/query_range" --data-urlencode 'query={job="varlogs"}' | jq
{
  "status": "success",
  "data": {
    "resultType": "streams",
    "result": [
      {
        "stream": {
          "filename": "/var/log/myproject.log",
          "job": "varlogs",
          "level": "info"
        },
        "values": [
          {
            "1569266497240578000",
            "foo"
          },
          {
            "1569266492548155000",
            "bar"
          }
        ]
      }
    ]
  }
}

`GET /loki/api/v1/label`

/loki/api/v1/label retrieves the list of known labels within a given time span. Itaccepts the following query parameters in the URL:

start: The start time for the query as a nanosecond Unix epoch. Defaults to 6 hours ago.
end: The start time for the query as a nanosecond Unix epoch. Defaults to now.

In microservices mode, /loki/api/v1/label is exposed by the querier.

Response:

{
  "values": [
    <label string>,
    ...
  ]
}

Examples

$ curl -G -s  "http://localhost:3100/loki/api/v1/label" | jq
{
  "values": [
    "foo",
    "bar",
    "baz"
  ]
}

`GET /loki/api/v1/label/<name>/values`

/loki/api/v1/label/<name>/values retrieves the list of known values for a givenlabel within a given time span. It accepts the following query parameters inthe URL:

start: The start time for the query as a nanosecond Unix epoch. Defaults to 6 hours ago.
end: The start time for the query as a nanosecond Unix epoch. Defaults to now.

In microservices mode, /loki/api/v1/label/<name>/values is exposed by the querier.

Response:

{
  "values": [
    <label value>,
    ...
  ]
}

Examples

$ curl -G -s  "http://localhost:3100/loki/api/v1/label/foo/values" | jq
{
  "values": [
    "cat",
    "dog",
    "axolotl"
  ]
}

`GET /loki/api/v1/tail`

/loki/api/v1/tail is a WebSocket endpoint that will stream log messages based ona query. It accepts the following query parameters in the URL:

query: The LogQL query to perform
delay_for: The number of seconds to delay retrieving logs to let slow loggers catch up. Defaults to 0 and cannot be larger than 5.
limit: The max number of entries to return
start: The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago.

In microservices mode, /loki/api/v1/tail is exposed by the querier.

Response (streamed):

{
  "streams": [
    {
      "stream": {
        <label key-value pairs>
      },
      "values": [
        [
          <string: nanosecond unix epoch>,
          <string: log line>
        ]
      ]
    }
  ],
  "dropped_entries": [
    {
      "labels": {
        <label key-value pairs>
      },
      "timestamp": "<nanosecond unix epoch>"
    }
  ]
}

`POST /loki/api/v1/push`

Alias (DEPRECATED): POST /api/prom/push

/loki/api/v1/push is the endpoint used to send log entries to Loki. The defaultbehavior is for the POST body to be a snappy-compressed protobuf messsage:

Alternatively, if the Content-Type header is set to application/json, aJSON post body can be sent in the following format:

{
  "streams": [
    {
      "labels": "<LogQL label key-value pairs>",
      "entries": [
        {
          "ts": "<RFC3339Nano string>",
          "line": "<log line>"
        }
      ]
    }
  ]
}

NOTE: logs sent to Loki for every stream must be in timestamp-ascendingorder, meaning each log line must be more recent than the one last received.If logs do not follow this order, Loki will reject the log with an out oforder error.

In microservices mode, /loki/api/v1/push is exposed by the distributor.

Examples

$ curl -H "Content-Type: application/json" -XPOST -s "https://localhost:3100/loki/api/v1/push" --data-raw \
  '{"streams": [{ "labels": "{foo=\"bar\"}", "entries": [{ "ts": "2018-12-18T08:28:06.801064-04:00", "line": "fizzbuzz" }] }]}'

`GET /api/prom/tail`

DEPRECATED: /api/prom/tail is deprecated. Use /loki/api/v1/tailinstead.

/api/prom/tail is a WebSocket endpoint that will stream log messages based ona query. It accepts the following query parameters in the URL:

query: The LogQL query to perform
delay_for: The number of seconds to delay retrieving logs to let slow loggers catch up. Defaults to 0 and cannot be larger than 5.
limit: The max number of entries to return
start: The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago.

In microservices mode, /api/prom/tail is exposed by the querier.

Response (streamed):

{
  "streams": [
    {
      "labels": "<LogQL label key-value pairs>",
      "entries": [
        {
          "ts": "<RFC3339Nano timestamp>",
          "line": "<log line>"
        }
      ]
    }
  ],
  "dropped_entries": [
    {
      "Timestamp": "<RFC3339Nano timestamp>",
      "Labels": "<LogQL label key-value pairs>"
    }
  ]
}

dropped_entries will be populated when the tailer could not keep up with theamount of traffic in Loki. When present, it indicates that the entries receivedin the streams is not the full amount of logs that are present in Loki. Notethat the keys in dropped_entries will be sent as uppercase Timestampand Labels instead of labels and ts like in the entries for the stream.

As the response is streamed, the object defined by the response format abovewill be sent over the WebSocket multiple times.

`GET /api/prom/query`

WARNING: /api/prom/query is DEPRECATED; use /loki/api/v1/query_rangeinstead.

/api/prom/query supports doing general queries. The URL query parameterssupport the following values:

query: The LogQL query to perform
limit: The max number of entries to return
start: The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago.
end: The start time for the query as a nanosecond Unix epoch. Defaults to now.
direction: Determines the sort order of logs. Supported values are forward or backward. Defaults to backward.
regexp: a regex to filter the returned results

In microservices mode, /api/prom/query is exposed by the querier.

Note that the larger the time span between start and end will causeadditional load on Loki and the index store, resulting in slower queries.

Response:

{
  "streams": [
    {
      "labels": "<LogQL label key-value pairs>",
      "entries": [
        {
          "ts": "<RFC3339Nano string>",
          "line": "<log line>"
        },
        ...
      ],
    },
    ...
  ]
}

Examples

$ curl -G -s  "http://localhost:3100/api/prom/query" --data-urlencode '{foo="bar"}' | jq
{
  "streams": [
    {
      "labels": "{filename=\"/var/log/myproject.log\", job=\"varlogs\", level=\"info\"}",
      "entries": [
        {
          "ts": "2019-06-06T19:25:41.972739Z",
          "line": "foo"
        },
        {
          "ts": "2019-06-06T19:25:41.972722Z",
          "line": "bar"
        }
      ]
    }
  ]
}

Examples

$ curl -H "Content-Type: application/json" -XPOST -s "https://localhost:3100/loki/api/v1/push" --data-raw \
  '{"streams": [{ "labels": "{foo=\"bar\"}", "entries": [{ "ts": "2018-12-18T08:28:06.801064-04:00", "line": "fizzbuzz" }] }]}'

`GET /ready`

/ready returns HTTP 200 when the Loki ingester is ready to accept traffic. Ifrunning Loki on Kubernetes, /ready can be used as a readiness probe.

In microservices mode, the /ready endpoint is exposed by all components.

`POST /flush`

/flush triggers a flush of all in-memory chunks held by the ingesters to thebacking store. Mainly used for local testing.

In microservices mode, the /flush endpoint is exposed by the ingester.

`GET /metrics`

/metrics exposes Prometheus metrics. SeeObserving Lokifor a list of exported metrics.

In microservices mode, the /metrics endpoint is exposed by all components.