API automation

API reference: Reference

You can use the API to request and download query logs programmatically.


The following utilities are recommended for the programming language you’re using:

  • An HTTP client

  • A JSON processor

  • A Fauna driver.

Example program

This example program shows you how to use an account key to fetch logs programmatically. You can extend the program to act on another Region Group or time interval. It can be extended further to fetch logs using the resulting presigned_url and exporting them to your observability platform.

To run the program, set the ACCOUNT_KEY environment variable to an account key in your Fauna account.

The general program flow is:

  1. Set up the endpoints and request headers, including the account key.

  2. Submit a log request (POST).

  3. Poll on log availability, an error, or timeout status (GET).


const axios = require('axios').default;
const winston = require('winston');
const lux = require("luxon");

const frontdoorClient = axios.create({
  baseURL: "https://frontdoor.fauna.com",
  timeout: 10000,

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  defaultMeta: { service: 'querylogs-demo' },
  transports: [
    new winston.transports.Console({
      level: "debug",
      handleExceptions: true,
      // enable json output, good to send to DD
      format: winston.format.json(),

const today = lux.DateTime.now().toISO();
const yesterday = lux.DateTime.now().minus(lux.Duration.fromISO("P1D")).toISO();

async function getLogs() {
  const headers = { Authorization: `Bearer ${process.env["ACCOUNT_KEY"]}` };
  const { data: querylogRequest } = await frontdoorClient.post(
    { region_group: "us-std", time_start: yesterday, time_end: today},
    { headers }
  await pollResults(querylogRequest, headers, "us-std");

if (process.env["ACCOUNT_KEY"] === undefined) {
  logger.error("You must set ACCOUNT_KEY in your local environment to run this program!");

async function pollResults(
) {
  let result;
  const maxRuntimeMs = 300 * 1000;
  const time_start = Date.now();
  do {
    ({ data: result } = await frontdoorClient.get(
      { headers }
    await new Promise((resolve) => setTimeout(resolve, 1000));
    logger.info(`State: ${result.state}`);
  } while (
    Date.now() < time_start + maxRuntimeMs &&
    !(["Complete", "DoesNotExist", "Failed", "TimedOut"].includes(result.state))
  return result;

getLogs().then(() => logger.info("Thanks for trying out Fauna logs! Please give us any and all feedback!"));

Trace queries

A trace uniquely identifies a transaction flow. In distributed scenarios, a traceparent propagates a contextual identifier, which lets you associate logs from disparate services that participate in the application. The traceparent request header represents a request in a tracing system using a common format. See traceparent.

Fauna query log supports distributed tracing by allowing you to apply a traceparent header to individual queries. The traceparent request header format is similar to this example:
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01.

You use the identifier in the query response in subsequent queries. If the Fauna query logic is not the main application, you should use the identifier provided by that application and follow the recommended processing model for mutating the identifier.

If you don’t include a traceparent identifier, one is generated for you and attached to the query response.


Because the query logs can be large and expensive to store and transmit, the query body is not included. Instead, you can tag individual queries with identifiers that can be used to associate operations.

You have the option of specifying an x-fauna-tags header tag, which is then propagated and included in the query logs emitted to disk.

  • Tags and associated values can be alphanumeric strings and include the underscore (_) character.

  • Tag names can be up to 40 characters, and tag values can be up to 80 characters.

  • You can have up to 25 tags per query.

A query fails with a 400 status code if the tag is invalid.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!