API docs by Redocly

Fauna Account HTTP API

Download OpenAPI specification:Download

Run In Postman

The Fauna Account HTTP API lets you manage features of a Fauna account. For example, you can use the API to:

Base URL

Account API endpoints use https://account.fauna.com as the base URL.

For example, the full URL for the /api/v1/logs (Request Query Logs) is https://account.fauna.com/api/v1/logs.

Fauna routes requests to accounts based on the account key secret used for authentication.

Authentication

You authenticate with the Account API using an account key's secret. Account keys are different from keys used for query requests.

Create an account key

You can create an account key in the Fauna Dashboard.

  1. Log in to the Fauna Dashboard.

  2. Click Account Keys.

  3. Click Create Key.

  4. Enter a Name and an optional TTL. The TTL is the number of days until the account key expires.

  5. Click Create.

  6. Copy the Key Secret.

Exports

Use the Export endpoints to create a point-in-time snapshot of a database or specified database collections and store their document data as JSON files in an AWS S3 bucket.

You can use exports to load Fauna data into third-party systems or store a Fauna data for compliance or data control. For more information, see snapshot export.

Export endpoints are in beta. To use the endpoints, you must:

  • Have an Enterprise plan.
  • Use an account key with the owner, admin, or developer role for your Fauna account. See Team management.

Create Export endpoint

Requests the export of a database or specific database collections to a provided AWS S3 bucket. The export operation is asynchronous. Fauna processes one export per account at a time.

By default, requests are not idempotent. To ensure idempotency, include a unique string in the Idempotency-Key HTTP request header. If a request with a matching idempotency key has already been processed successfully, the same response is returned without reprocessing the request.

Idempotency keys are scoped to the request's account API key. Using the same idempotency key with different API keys will not result in idempotent requests.

This endpoint is in beta. To use the endpoint, you must:

  • Have an Enterprise plan.
  • Use an account key with the owner, admin, or developer role for your Fauna account. See Team management.
Authorizations:
bearerAuth
header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Idempotency-Key
string
Example: abc12345

Unique string used to ensure idempotency of the request. If a request with the same Idempotency-Key has already been processed successfully, the same response will be returned without reprocessing the request.

Idempotency keys are scoped to the request's account API key. Using the same idempotency key with different API keys will not result in idempotent requests.

Request Body schema: application/json
required
database
required
string

Path for the database, including the region group identifier and hierarchy, to export. Separate path components using /. Examples: us-std/my_db, eu-std/parent_db/child_db, global/db.

Child databases are not included in the export.

collections
Array of strings

Used-defined collections from the database to export. If not present, all user-defined collections are exported. You can't export system collections.

format
required
string
Enum: "tagged" "simple"

Data format used to convert the export's FQL document data to JSON. Accepts tagged or simple.

required
string or object

Configuration for the AWS S3 bucket path used to store exported data. The S3 bucket must grant permissions to Fauna's IAM role. See S3 bucket permissions.

Responses

Request samples

Content type
application/json
{
  • "database": "us-std/parent_db/child_db",
  • "collections": [
    • "Product",
    • "Category"
    ],
  • "format": "simple",
  • "destination": "s3://doc-example-bucket/fauna_exports/parent_db/child_db/2099-12-31"
}

Response samples

Content type
application/json
{
  • "response": {
    • "id": 123456789,
    • "state": "Pending",
    • "database": "us-std/parent_db/child_db",
    • "format": "simple",
    • "destination": {
      • "s3": {
        • "bucket": "doc-example-bucket",
        • "path": "fauna_exports/parent_db/child_db/2099-12-31/"
        },
      • "uri": "s3://doc-example-bucket/fauna_exports/parent_db/child_db/2099-12-31/"
      },
    • "created_at": "2099-12-31T21:46:12.580Z",
    • "updated_at": "2099-12-31T21:46:12.580Z",
    • "is_terminal": false,
    • "collections": [
      • "Product",
      • "Category"
      ]
    }
}

List Exports endpoint

Get a list of all exports for the account. You can optionally filter exports by state or database. Exports are ordered by state and descending export ID.

This endpoint is in beta. To use this endpoint, you must:

  • Have an Enterprise plan.
  • Use an account key with the owner, admin, or developer role for your Fauna account. See Team management.
Authorizations:
bearerAuth
query Parameters
next_token
string or null
Example: next_token=slkdj823knl

Pagination token used to retrieve the next page of results.

max_results
integer or null
Default: 10
Example: max_results=100

Maximum number of items to return per page. Accepts 1 to 1000. Defaults to 10.

state
string
Enum: "Pending" "InProgress" "Complete" "Failed"
Example: state=Pending

Filter results by the current state of the export. Accepts one of the following:

  • Pending: The export request has been received but is not yet in progress.
  • InProgress: The export is in progress. This includes copying the export files to the S3 bucket.
  • Complete: The export is complete. Export files are available in the S3 bucket.
  • Failed: There was an error processing the export.

You can pass this parameter multiple times to filter on multiple states.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Responses

Request samples 

curl -X GET \
  --get \
  'https://account.fauna.com/v2/exports' \
  -H "Authorization: Bearer $ACCOUNT_KEY_SECRET" \
  --data-urlencode 'state=Pending' \
  --data-urlencode 'state=Complete' \
  --data-urlencode 'database=us-std/parent_db/child_db'

Response samples

Content type
application/json
{
  • "response": {
    • "results": [
      • {
        • "id": "419712383276024405",
        • "state": "Pending",
        • "database": "us-std/parent_db/child_db",
        • "format": "simple",
        • "destination": {
          • "s3": {
            • "bucket": "doc-example-bucket",
            • "path": "fauna_exports/parent_db/child_db/2099-12-29"
            },
          • "uri": "s3://doc-example-bucket/fauna_exports/parent_db/child_db/2099-12-2"
          },
        • "created_at": "2099-12-29T16:49:30.149868Z",
        • "updated_at": "2099-12-29:49:30.149868Z",
        • "is_terminal": false,
        • "collections": [
          • "Product",
          • "Category"
          ]
        },
      • {
        • "id": "419714480594747987",
        • "state": "InProgress",
        • "database": "us-eu/my_db",
        • "format": "simple",
        • "destination": {
          • "s3": {
            • "bucket": "doc-example-bucket",
            • "path": "fauna_exports/my_db/2099-12-30"
            },
          • "uri": "s3://doc-example-bucket/fauna_exports/my_db/2099-12-30"
          },
        • "created_at": "2099-12-30T17:22:50.310371Z",
        • "updated_at": "2025-12-30T17:22:50.310371Z",
        • "is_terminal": false
        },
      • {
        • "id": "419714495398543955",
        • "state": "Complete",
        • "database": "global/my_prod_db",
        • "format": "simple",
        • "destination": {
          • "s3": {
            • "bucket": "doc-example-bucket",
            • "path": "fauna_exports/my_prod_db/2099-12-31"
            },
          • "uri": "s3://doc-example-bucket/fauna_exports/my_prod_db/2099-12-31"
          },
        • "created_at": "2025-12-31T17:23:04.433829Z",
        • "updated_at": "2025-12-31T17:23:04.433829Z",
        • "is_terminal": true
        },
      • {
        • "id": "419714495398543955",
        • "state": "Failed",
        • "database": "global/my_prod_db",
        • "format": "simple",
        • "destination": {
          • "s3": {
            • "bucket": "doc-example-bucket",
            • "path": "fauna_exports/my_prod_db/2099-12-31"
            },
          • "uri": "s3://doc-example-bucket/fauna_exports/my_prod_db/2099-12-31"
          },
        • "created_at": "2025-12-31T15:23:04.433829Z",
        • "updated_at": "2025-12-31T15:23:04.433829Z",
        • "is_terminal": true,
        • "collections": [
          • "Product",
          • "Category"
          ],
        • "state_info": {
          • "code": "configuration_error",
          • "message": "Fauna cannot access bucket \\'doc-example-bucket\\'. Please verify the bucket name and configuration."
          }
        }
      ]
    }
}

Get Export endpoint

Get an export by its ID.

This endpoint is in beta. To use this endpoint, you must:

  • Have an Enterprise plan.
  • Use an account key with the owner, admin, or developer role for your Fauna account. See Team management.
Authorizations:
bearerAuth
path Parameters
export_id
required
string
Example: 123456789

ID of the export to retrieve.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Responses

Request samples 

curl -X GET \
  'https://account.fauna.com/v2/exports/<EXPORT_ID>' \
  -H "Authorization: Bearer $ACCOUNT_KEY_SECRET"

Response samples

Content type
application/json
Example
{
  • "response": {
    • "id": "123456789",
    • "state": "Pending",
    • "database": "us-std/parent_db/child_db",
    • "collections": [
      • "Product",
      • "Category"
      ],
    • "format": "simple",
    • "destination": {
      • "s3": {
        • "bucket": "doc-example-bucket",
        • "path": "fauna_exports/parent_db/child_db/2099-12-31"
        },
      • "uri": "s3://doc-example-bucket/fauna_exports/parent_db/child_db/2099-12-31"
      },
    • "created_at": "2099-12-31T21:46:12.580Z",
    • "updated_at": "2099-12-31T21:46:12.580Z",
    • "is_terminal": false
    }
}

Fauna Logs

Use the Fauna Logs endpoints to programmatically request and fetch query logs. You can use Fauna Logs to monitor the performance of your Fauna databases and diagnose issues.

For an overview of the API workflow and an example implementation, see Access Fauna Logs using the HTTP API.

Request Fauna Logs endpoint

Requests a set of Fauna Logs.

The operation is asynchronous. The response contains a request ID. To check the status of the request, pass the ID to the Get Fauna Logs Request Status endpoint.

Authorizations:
bearerAuth
query Parameters
type
required
string
Example: type=query

Type of logs to retrieve. Valid value is query.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Request Body schema: application/json
required
database
string

Path to a database including the region group identifier and hierarchy, to get logs for. Separate path components using /. Examples: us-std/my_db, eu-std/parent_db/child_db, global/db.

Omit this parameter to get logs for all databases in a region group.

region_group
string

Region group to get logs for. Accepted values are classic, us-std, and eu-std.

If requesting logs for a specific database, omit this parameter. If you provide the database parameter, region_group is ignored.

time_start
required
string <date-time>

ISO 8601 timestamp for the log start time (inclusive). Can not be:

  • More than 90 days before time_end.
  • Before January 18, 2023 UTC.
  • More than 1 year from the current date.
time_end
required
string <date-time>

ISO 8601 timestamp for the log end time (exclusive).

idempotency_token
string <uuid>

Optional idempotency token. If the same idempotency_token is used for multiple requests within 24 hours, each is treated as the same request.

Responses

Request samples

Content type
application/json
{
  • "database": "us-std/parent_db/child_db",
  • "region_group": "us-std",
  • "time_start": "2099-09-19T20:42:16.828Z",
  • "time_end": "2019-08-24T14:15:22Z",
  • "idempotency_token": "813831FE-8F2A-423F-9467-55551F784250"
}

Response samples

Content type
application/json
{
  • "request_id": "123456",
  • "database": "us-std/parent_db/child_db",
  • "region_group": "us-std",
  • "state": "Complete",
  • "time_start": "2099-09-19T20:42:16.828Z",
  • "time_end": "2099-09-19T20:42:16.828Z",
  • "updated_at": "2099-09-19T20:42:16.828Z",
  • "version": 0
}

Get Fauna Logs Request Status endpoint

Gets the status of a Fauna Logs request. You can submit a request using the Request Fauna Logs endpoint.

If the request is complete, the response includes a presigned URL for the log file, compressed using gzip. For the log schema, see Log record format.

The presigned URL expires at a time provided in the response. To request a new URL after expiration, use the Create Fauna Logs File URL endpoint.

Authorizations:
bearerAuth
path Parameters
request_id
required
string
Example: 123456

Log request ID, returned by the Request Fauna Logs endpoint.

query Parameters
type
required
string
Example: type=query

Type of logs to retrieve. Valid value is query.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Responses

Request samples 

curl -X GET \
  'https://account.fauna.com/api/v1/logs/123456?type=query' \
  -H "Authorization: Bearer $ACCOUNT_KEY_SECRET"

Response samples

Content type
application/json
{
  • "request_id": "123456",
  • "database": "us-std/parent_db/child_db",
  • "presigned_url": "https://link.to.your.logs.com",
  • "presigned_url_expiration_time": "2099-09-19T21:42:16.828Z",
  • "region_group": "classic",
  • "state": "Complete",
  • "time_start": "2099-09-19T20:42:16.828Z",
  • "time_end": "2099-09-19T20:42:16.828Z",
  • "updated_at": "2099-09-19T20:42:16.828Z",
  • "version": 0
}

Create Fauna Logs File URL endpoint

Creates a new presigned URL for a log file from a completed log request.

If a Fauna logs request is complete, the Get Fauna Logs Request Status endpoint returns a a presigned URL for the log file. The presigned URL expires at a provided time.

You typically use this endpoint to request a presigned URL after a previous presigned URL expires.

Authorizations:
bearerAuth
path Parameters
request_id
required
string
Example: 123456

Request ID associated with the logs - returned by the /api/v1/logs POST request.

query Parameters
type
required
string
Example: type=query

Type of logs to retrieve. Valid value is query.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Request Body schema: application/json
optional

Optional request body for controlling URL creation.

version
integer

Optional optimistic lock version of the log.

Responses

Request samples

Content type
application/json
{
  • "version": 1
}

Response samples

Content type
application/json
{
  • "request_id": "123456",
  • "database": "us-std/parent_db/child_db",
  • "region_group": "us-std",
  • "state": "Complete",
  • "time_start": "2099-09-19T20:42:16.828Z",
  • "time_end": "2099-09-19T20:42:16.828Z",
  • "updated_at": "2099-09-19T20:42:16.828Z",
  • "version": 0
}

List Fauna Log Requests endpoint

Gets a list of log requests for the account.

If a request is complete, the request item includes a presigned URL for the log file and its expiration timestamp.

Authorizations:
bearerAuth
query Parameters
type
required
string
Example: type=query

The type of logs to retrieve (e.g. query).

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Request Body schema: application/json
required

Inputs bounding the logs you want to list.

states
required
Array of strings (LogState)

State of log requests to retrieve. Cannot be empty.

Valid values are:

  • Pending: Fauna received the request.
  • Requested: Logs are submitted for extraction.
  • Failed: Request operation failed.
  • TimedOut: Request operation timed out.
  • Complete: Request operation complete.
  • CreatingNewUrl: Request operation complete. Creating new presigned URL for log file.
  • DoesNotExist: Requested logs don't exist.
next_token
string or null

Pagination token used to retrieve the next page of results.

If omitted, the first page is retrieved.

max_results
integer

Maximum number of items to return per page. Must be 1 or greater.

Responses

Request samples

Content type
application/json
{
  • "states": [
    • "Complete",
    • "Requested"
    ],
  • "next_token": "slkdj823knl",
  • "max_results": 100
}

Response samples

Content type
application/json
{
  • "next_token": "slkdj823knl",
  • "results": [
    • {
      • "request_id": "123456",
      • "database": "us-std/parent_db/child_db",
      • "region_group": "us-std",
      • "state": "Complete",
      • "time_start": "2099-09-19T20:42:16.828Z",
      • "time_end": "2099-09-19T20:42:16.828Z",
      • "updated_at": "2099-09-19T20:42:16.828Z",
      • "version": 1,
      • "presigned_url": "https://link.to.your.logs.com",
      • "presigned_url_expiration_time": "2019-08-24T14:15:22Z"
      }
    ]
}

OAuth 2.0 Apps

Some integrations, such as the Cloudflare Worker integration, automatically create an OAuth client app in your Fauna account when you connect them.

You can use the OAuth 2.0 Apps endpoints to manage OAuth apps for your Fauna account. The endpoints mirror the functionality of the Fauna Dashboard's OAuth Apps page.

List OAuth Apps endpoint

List the OAuth apps authorized for your Fauna account.

Authorizations:
bearerAuth
query Parameters
next_token
string or null
Example: next_token=slkdj823knl

Pagination token used to retrieve the next page of results.

max_results
integer
Example: max_results=100

Maximum number of items to return per page. Must be 1 or greater.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Responses

Request samples 

curl -X GET \
  'https://account.fauna.com/api/v1/oauth/apps' \
  -H "Authorization: Bearer $ACCOUNT_KEY_SECRET"

Response samples

Content type
application/json
{
  • "next_token": "slkdj823knl",
  • "results": [
    • {
      • "id": "12311231",
      • "oauth2_client": "Cloudflare",
      • "scope": [
        • {
          • "id": "list_databases",
          • "display_name": "List Databases"
          }
        ],
      • "created_at": "2022-09-19T20:42:16.828Z"
      }
    ]
}

Delete OAuth App endpoint

Deletes an OAuth app authorized for your Fauna account.

Deleting the app disables the integration. Once deleted, the integration can no longer access your Fauna account.

Authorizations:
bearerAuth
path Parameters
id
required
string (Id)
Example: 12311231

ID of the OAuth app to delete.

You can get an ID using the List OAuth Apps endpoint.

header Parameters
Authorization
required
string
Example: Bearer <ACCOUNT_KEY_SECRET>

A Fauna account key's secret, passed as a bearer token.

Account keys are different from keys used for query requests. See Authentication.

Responses

Request samples 

curl -X DELETE \
  'https://account.fauna.com/api/v1/oauth/apps/{id}' \
  -H "Authorization: Bearer $ACCOUNT_KEY_SECRET"

Response samples

Content type
application/json
{
  • "reason": "Invalid request."
}

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!