API docs by Redocly

Fauna Account API

Download OpenAPI specification:Download

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) endpoint 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 and click Account in the left navigation.

  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.

Query Logs

Use the Query Logs endpoints to programmatically request and fetch query logs. You can use query 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 query logs using the HTTP API.

Request Query Logs

Requests a set of query logs.

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

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

Type of logs to retrieve. Valid value is query.

Request Body schema: application/json
required
database
string

Path, including the region group and hierarchy, for the database to get logs for. Separate path components using /. For example: us-std/production/customers or us-std/development/customers.

Omit this parameter to get logs for all databases for 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/production/customers",
  • "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/production/customers",
  • "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 Query Logs Request Status

Gets the status of a query logs request. You can submit a request using the Request Query 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 Query Logs File URL endpoint.

Authorizations:
bearerAuth
path Parameters
request_id
required
string
Example: 123456

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

query Parameters
type
required
string
Example: type=query

Type of logs to retrieve. Valid value is query.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "request_id": "123456",
  • "database": "us-std/production/customers",
  • "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 Query Logs File URL

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

If a query logs request is complete, the Get Query 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.

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/production/customers",
  • "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 Query Log Requests

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

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

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 retrieve. 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/production/customers",
      • "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

List the OAuth apps authorized for your Fauna account.

Authorizations:
bearerAuth
query Parameters
next_token
string
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 retrieve. Must be 1 or greater.

Responses

Request samples 

curl --request GET \
  --url 'https://account.fauna.com/api/v1/oauth/apps' \
  --header '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

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.

Responses

Request samples 

curl --request DELETE \
  --url 'https://account.fauna.com/api/v1/oauth/apps/{id}' \
  --header 'Authorization: Bearer $ACCOUNT_KEY_SECRET'

Response samples

Content type
application/json
{
  • "reason": "Details about the error"
}

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!