GraphQL Endpoint

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

API	Endpoint
Publisher	`http://localhost:3000/auditlog/publisher/v1/project/{project_id}/graphql`
Admin	`http://localhost:3000/auditlog/admin/v1/project/{project_id}/environment/{environment_id}/graphql`
Enterprise	`http://localhost:3000/auditlog/enterprise/v1/graphql`
Viewer	`http://localhost:3000/auditlog/viewer/v1/graphql`
Viewer Paginated by page size and offset	`http://localhost:3000/auditlog/viewer/v1/graphql/paginated`

Search

This query is used for the GraphQL API with cursor pagination. 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:Germany',
  last: 50,
  before: 'opaquecursor',
};
const res = fetch(
  'http://localhost:3000/auditlog/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,
    }),
  }
);

Search by page size and offset

For GraphQL API with page size & page limit based pagination, you can use the following query.

{
  searchPaginated(query:"action:user.login location:Germany", pageOffset: 0, pageLimit: 20, startCursor: "", sortOrder: "desc") {
    totalCount
    edges {
      cursor
      node {
        action
        actor {
          name
        }
        created
        country
      }
    }
  }
}

Variables

Use query, pageOffset, pageLimit, sortOrder and startCursor variables to enable reuse of your query templates. If you define a parameterized query like this...

const searchQuery = `query SearchPaginated($query: String!, $pageOffset: Int!, $pageLimit: Int!, $startCursor: String, $sortOrder: sortOrder) {
  searchPaginated(query: $query, pageOffset: $pageOffset, pageLimit: $pageLimit, startCursor: $startCursor, sortOrder: $sortOrder) {
    totalCount
    edges {
      cursor
      node {
        action
        actor {
          name
        }
        created
        country
      }
    }
  }
}`;

... then you can execute searches like this:

const vars = {
  query: 'action:user.login location:Germany',
  pageOffset: 0,
  pageLimit: 20,
  startCursor: 'opaquecursor',
  sortOrder: 'desc',
};
const res = fetch(
  'http://localhost:3000/auditlog/viewer/v1/graphql/paginated',
  {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      Authorization:
        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJhZjFmYzY5NzhhNzRmZGZhMWJmMzI3MjlmZjRhZTYyIiwicHJvamVjdElkIjoiZGV2IiwiZW52aXJvbmiu7nRJZCI6ImRldiIsImdyb3VwSWQiOiIyMmQ4NzVhMS01YTI3LTQ2NjMtOTBlYi1iNGU3Yjk3ZGFhODAiLCJ2aWV3T896QWN0aW9uIjoiYXVkaXQubG9nLnZpZXciLCJhY3RvcklkIjoiYWRtaW4iLCJjcmVhdGVkIjoxNzIyOTIyMzc3MDAwLCJzY29wZSI6IiIsImlwIjoiMTkyLjE2OC42NS4xIiwiaWF0IjoxNzIyOTIyMzgwfQ.MIzMboQLvQxI5Xh7g3L-qjTl8qR9sXu5po2psVmz-Y4',
    },
    body: JSON.stringify({
      query: searchQuery,
      variables: vars,
    }),
  }
);

Schema Types

Table of Contents

Schema Types
- Query
- Objects
  - SearchEventEdge
  - SearchQueryResult
  - PaginatedSearchQueryResult
  - Action
  - Actor
  - Display
  - Event
  - Field
  - Group
  - PageInfo
  - Target
- Enums
  - CRUD
  - SortOrder
- Scalars
  - Boolean
  - ID
  - Int
  - String

Query

The root query object of the Retraced GraphQL interface.

Field	Type	Description
search	SearchQueryResult	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.
searchPaginated	PaginatedSearchQueryResult	Run a paginated advanced search for events.
query	String	The structured search operators used to filter events.
pageOffset	Int	The number of events to offset from the start of the results.
pageLimit	Int	The maximum number of results per page.
startCursor	String	A cursor returned from the first event of the first page to make sure the window of events in maintained.
sortOrder	SortOrder	The order to sort the results in.

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	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	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 Retraced 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 Retraced API.

SearchEventEdge

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.

SearchQueryResult

The results of a search query.

Field	Type	Description
edges	[SearchEventEdge]	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.

PaginatedSearchQueryResult

The results of hte paginated search query.

Field	Argument	Type	Description
edges		[SearchEventEdge]	The events and cursors matching the query.
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	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

SortOrder

Ascending | Descending

Value	Description
asc	Ascending
desc	Descending

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.

Search​

Variables​

Search by page size and offset​

Variables​

Schema Types

Query​

Objects​

Action​

Actor​

Display​

Event​

SearchEventEdge​

SearchQueryResult​

PaginatedSearchQueryResult​

Field​

Group​

PageInfo​

Target​

Enums​

CRUD​

SortOrder​

Scalars​

Boolean​

ID​

Int​

String​

Search

Variables

Search by page size and offset

Variables

Query

Objects

Action

Actor

Display

Event

SearchEventEdge

SearchQueryResult

PaginatedSearchQueryResult

Field

Group

PageInfo

Target

Enums

CRUD

SortOrder

Scalars

Boolean

ID

Int

String