GraphQL Endpoint

Events in an audit log must be ordered

The recommended way to search events using an API is to POST your query and variables to the appropriate Audit Log GraphQL endpoint.

API Endpoint
Publisher https://api.retraced.io/publisher/v1/project/{projectId}/graphql
Admin https://api.retraced.io/admin/v1/project/{projectId}/environment/{environmentId}/graphql
Enterprise https://api.retraced.io/enterprise/v1/graphql
Viewer https://api.retraced.io/viewer/v1/graphql

The query root provides a search method. A fully-formed query for a subset of event fields would look like this:

{
  search(query:"action:user.login location:Germany", last:50, before:"opaquecursor") {
    totalCount
    pageInfo {
      hasNextPage
    }
    edges {
      cursor
      node {
        action
        actor {
          name
        }
        created
	country
      }
    }
  }
}

Variables

Use query, last, and before variables to enable reuse of your query templates. If you define a parameterized query like this…

const searchQuery = `query Search($query: String!, $last: Int, $before: String) {
  search(query:"action:user.login location:Germany", last:50, before:"opaquecursor") {
    totalCount
    pageInfo {
      hasNextPage
    }
    edges {
      cursor
      node {
        action
        actor {
          name
        }
        created
	country
      }
    }
  }
}`;

… then you can execute searches like this:

const vars = {
  query: "action:user.login location:German",
  last: 50,
  before: "opaquecursor",
};
const res = fetch("https://api.retraced.io/publisher/v1/project/3hf140713bn302/graphql", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Token token=2ba3059ad7f14071b9befb2a7a2e195e",
  },
  body: JSON.stringify({
    query: searchQuery,
    variables: vars,
  }),
});

Schema Types

Table of Contents

Query

The root query object of the GraphQL interface.

Field Argument Type Description
search EventsConnection Run an advanced search for events.
query String The structured search operators used to filter events.
first Int The limit of events to return, sorted from oldest to newest. It can optionally be used with the after argument.
after String A cursor returned from a previous query.
last Int The limit of events to return, sorted from newest to oldest. It can optionally be used with the before argument.
before String A cursor returned from a previous query.

Objects

Action

An action.

Field Argument Type Description
action String The action field of an event such as "user.login".

Actor

The agent who performed an event.

Field Argument Type Description
id ID A unique id representing this actor.
name String The name of this actor.
href String The URL associated with this actor.
fields [Field] The set of fields associated with this actor.

Display

Field Argument Type Description
markdown String

Event

A single record in an audit log.

Field Argument Type Description
id ID A unique id representing this event.
action String The type of action that was taken to generate this event.
description String The description of the event that was taken.
group Group The group associated with this event.
actor Actor The actor associated with this event.
target Target The target associated with this event.
crud CRUD The classification of this event as create, read, update, or delete.
display Display The display text for this event.
received String The time that the API received this event.
created String The time that this event was reported as performed.
canonical_time String The created time if specified; else the received time.
is_failure Boolean Set to true if the event represents a failed use of permissions.
is_anonymous Boolean Set to true if the user was not logged in when performing this action.
source_ip String The IP address of the actor when the action was performed.
country String The country that the actor was in when the action was performed.
loc_subdiv1 String The large area of the country the actor was in when the action was performed (State).
loc_subdiv2 String The granular area of the country the actor was in when the action was performed (City).
component String An identifier for the vendor app component that sent the event.
version String An identifier for the version of the vendor app that sent the event, usually a git SHA
fields [Field] The set of fields associated with this event.
raw String The raw event sent to the API.

EventEdge

The event and cursor for a single result.

Field Argument Type Description
node Event The event object.
cursor String An opaque cursor for paginating from this point in the search results. Use it as the after argument to paginate forward or the before argument to paginate backward.

EventsConnection

The results of a search query.

Field Argument Type Description
edges [EventEdge] The events and cursors matching the query.
pageInfo PageInfo Indications that more search results are available.
totalCount Int The total number of search results matched by the query.

Field

Field Argument Type Description
key String The key for this field.
value String The value for this field.

Group

The group this event is associated with.

Field Argument Type Description
id ID A unique id representing this group.
name String The name of this group.

PageInfo

Field Argument Type Description
hasNextPage Boolean When paging forward with first, indicates more results are available.
hasPreviousPage Boolean When paging backward with last, indicates more results are available.

Target

The object an event is performed on.

Field Argument Type Description
id ID A unique id representing this target.
name String The name of this target.
href String The URL associated with this target.
type String The type of this target entity.
fields [Field] The set of fields associated with this target.

Enums

CRUD

Create | Read | Update | Delete

Value Description
c create
r read
u update
d delete

Scalars

Boolean

The Boolean scalar type represents true or false.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Interfaces