Skip to content
MindflowMindflowMindflow Help Center

List audit logs

GET
/audit-logs
curl --request GET \
  --url 'https://api-dev.mindflow.io/v1/audit-logs?category=flow&fields=auditLogId%2Ccategory%2Ctimestamp&limit=100&before=2024-03-20T15%3A30%3A00Z&after=2024-03-19T00%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'

Retrieves a paginated list of audit logs with advanced filtering and pagination options.

Curl Examples

All requests require authentication: -H “Authorization: Bearer YOUR_API_KEY”

1. Basic list (default pagination)

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/audit-logs"

2. Filter by category

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/audit-logs?category=flow"

3. Select specific fields

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/audit-logs?fields=auditLogId,category,timestamp"

4. Date-based pagination (with ‘before’ and ‘limit’)

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/audit-logs?before=2024-03-20T15:30:00Z&limit=100"

5. Cursor-based pagination

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/audit-logs?cursor=eyJjdXJzb3IiOiIxMjM0NTYifQ==&limit=100"

6. Combined filters (category, fields, after, limit)

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/audit-logs?category=credential&fields=auditLogId,category,type,timestamp&after=2024-03-19T00:00:00Z&limit=50"

Pagination Strategies

This endpoint supports two mutually exclusive pagination strategies:

  1. Date-based filtering with cursor pagination

    • Use before and/or after to filter logs within a specific time range (ISO 8601 format).
    • limit is required when using before or after.
    • Use the returned cursor to continue paginating through filtered results.
    • The returned cursor is scoped to the applied date filters.

  2. Cursor-based pagination only

    • Use limit to set the page size.
    • Use cursor to navigate sequentially through all results, without date filtering.

Notes:

  • The cursor parameter cannot be used together with before or after.
  • Results are always sorted by timestamp in descending order (newest first).
  • The default page size is 100 items per request.
  • The maximum page size is 1000 items per request.

⚠️ Warning: If there are no audit logs matching the specified parameters for a continuous period of 72 hours, the request will return no logs.

Response Structure

  • auditLogs: Array of audit log entries matching the filter criteria. Each entry follows the AuditLogSummary schema.
  • pagination: Pagination metadata, including the next cursor and total count, as defined in PaginationResponse.

Error Handling

  • Returns detailed error responses for invalid parameters, authentication failures, rate limiting, and server errors. See referenced error schemas for details.

⚠️ Rate Limiting:
This endpoint is subject to rate limits. Exceeding the allowed number of requests will result in a 429 Too Many Requests error.
To avoid disruptions, implement exponential backoff or retry logic in your client, and monitor the Retry-After response header for guidance on when to retry.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
category
string
Allowed values: flow flow-deployment credential environment permission mcp team organization signup-email-domain

Filter audit logs by category. Available categories:

  • flow: Flow-related operations.
  • flow-deployment: Flow deployment activities.
  • credential: Credential management operations.
  • environment: Environment management operations.
  • permission: Permission and access control changes.
  • mcp: Model Context Protocol (HTTP MCP) invocations.
  • team: Team management operations.
  • organization: Organization lifecycle operations.
  • signup-email-domain: Signup email domain changes.

If not specified, logs from all categories are included.

Example
flow
fields
Array<string>
<= 6 items unique items
Allowed values: auditLogId category type timestamp expiresAt metadata

Specify which fields to include in each audit log entry. Available fields:

  • auditLogId: Unique identifier of the audit log (format: AUDI-{UUIDv4}).
  • category: Category of the audit log.
  • type: Type of operation recorded.
  • timestamp: When the operation occurred (ISO 8601 format).
  • expiresAt: When the log entry will expire (ISO 8601 format).
  • metadata: Additional context about the operation.

If not specified, all fields are included.

Example
?fields=auditLogId,category,timestamp
limit
integer format: int32
default: 100 >= 1 <= 1000

The maximum number of items to return per page. Defaults to 100 if not specified. Must be between 1 and 1000. Lower values reduce response time and memory usage. Higher values reduce the number of API calls needed but increase response time.

cursor
string
<= 1024 characters

An opaque token used for paginating through results. To fetch the next page, pass the nextCursor value received in the previous response. Cursor-based pagination ensures consistent results when the underlying data changes between requests, avoids skipping or duplicating items, and performs better than offset-based pagination. The cursor encodes the position in the result set and any filtering parameters that were used in the original request.

before
string format: date-time
<= 29 characters

Filter audit logs created before the specified timestamp (exclusive). Must be in ISO 8601 format (e.g., ‘2024-03-20T15:30:00Z’).

  • Cannot be used with the cursor parameter.
  • Requires limit to be specified.
Example
2024-03-20T15:30:00Z
after
string format: date-time
<= 29 characters

Filter audit logs created after the specified timestamp (exclusive). Must be in ISO 8601 format (e.g., ‘2024-03-19T00:00:00Z’).

  • Cannot be used with the cursor parameter.
  • Requires limit to be specified.
Example
2024-03-19T00:00:00Z

Responses

Section titled “Responses”

200

Section titled “200”

Successfully retrieved audit logs.

  • auditLogs: Array of audit log entries matching the filter criteria. Each entry follows the AuditLogSummary schema, which includes:
    • auditLogId: Unique identifier (AUDI-{UUIDv4}).
    • category: Log category.
    • type: Operation type.
    • timestamp: Event timestamp (ISO 8601).
    • createdAt: Log creation timestamp (ISO 8601).
    • expiresAt: Log expiration timestamp (ISO 8601).
    • metadata: Additional context (object, varies by category/type).
  • pagination: Pagination metadata as defined in PaginationResponse.
Media typeapplication/json
object
auditLogs
required
Array<object>
<= 1000 items

Response object for audit log entry.

object
auditLogId

Unique identifier of the audit log entry. This ID is immutable and serves as the primary key for audit log entries.

string
>= 1 characters <= 128 characters /^[^\p{C}]+$/
category

The category of the audit log entry, which determines the context and scope of the logged action. Valid categories are: ‘flow’ for flow-related operations, ‘flow-deployment’ for deployment-specific events, ‘credential’ for credential management actions, ‘environment’ for environment management actions, ‘permission’ for permission-related changes, ‘mcp’ for Model Context Protocol (HTTP MCP) activity, ‘team’ for team management actions, ‘organization’ for organization lifecycle operations, and ‘signup-email-domain’ for signup email domain changes.

string
Allowed values: flow flow-deployment credential environment permission mcp team organization signup-email-domain
type

The specific type of action or event that was logged. The value of this field is dependent on the category and provides detailed information about the nature of the audit event.

Audit Event Types

Category: flow-deployment

  • deploy_queued: Flow deployment deploy queued
  • deploy_started: Flow deployment deploy started
  • deploy_completed: Flow deployment deploy completed
  • deploy_failed: Flow deployment deploy failed
  • run_queued: Flow deployment run queued
  • run_started: Flow deployment run started
  • run_completed: Flow deployment run completed
  • run_failed: Flow deployment run failed
  • step_run_queued: Flow deployment step run queued
  • step_run_started: Flow deployment step run started
  • step_run_completed: Flow deployment step run completed
  • step_run_failed: Flow deployment step run failed

Category: flow

  • step_create: Creation of a new step in a flow
  • step_update: Update to an existing step in a flow
  • step_delete: Deletion of a step from a flow
  • link_create: Creation of a new link between steps
  • link_update: Update to an existing link between steps
  • link_delete: Deletion of a link between steps
  • flow_create: Creation of a new flow
  • flow_update: Update to an existing flow
  • flow_delete: Deletion of a flow
  • flow_move: Moving a flow between environments
  • flow_duplicate: Duplicating a flow
  • import_export: Importing entities into the system
  • ai_generate_flow_description: AI generation of a playbook description
  • ai_generate_flow: AI generation of a flow
  • revert: Reverting a changelog action

Category: permission

  • create_completed: Permission was successfully created
  • create_failed: Failed to create permission
  • update_completed: Permission was successfully updated
  • update_failed: Failed to update permission
  • delete_completed: Permission was successfully deleted
  • delete_failed: Failed to delete permission

Category: credential

  • create_completed: Credential was successfully created
  • create_failed: Failed to create credential
  • update_completed: Credential was successfully updated
  • update_failed: Failed to update credential
  • delete_completed: Credential was successfully deleted
  • delete_failed: Failed to delete credential
  • update_value_completed: Credential value was successfully updated
  • update_value_failed: Failed to update credential value
  • get_completed: Credential value was successfully accessed/decrypted
  • get_failed: Failed to access credential value

Category: environment

  • create_completed: Environment was successfully created
  • create_failed: Failed to create environment
  • update_completed: Environment was successfully updated
  • update_failed: Failed to update environment
  • delete_completed: Environment was successfully deleted
  • delete_failed: Failed to delete environment

Category: mcp

  • invocation_completed: An MCP JSON-RPC request completed successfully
  • invocation_failed: An MCP JSON-RPC request failed with an error

Category: team

  • create_completed: Team was successfully created
  • create_failed: Failed to create team
  • update_completed: Team was successfully updated
  • update_failed: Failed to update team
  • delete_completed: Team was successfully deleted
  • delete_failed: Failed to delete team

Category: organization

  • create_completed: Organization was successfully created
  • create_failed: Failed to create organization
  • update_completed: Organization was successfully updated
  • update_failed: Failed to update organization
  • delete_completed: Organization was successfully deleted
  • delete_failed: Failed to delete organization

Category: signup-email-domain

  • add_completed: An email domain was allowed to sign up
  • remove_completed: An email domain was removed from the signup list
string
<= 50 characters /^[a-z_]+$/
timestamp

The exact date and time when the audited event occurred, recorded in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssZ). This timestamp is set at the moment the event is logged and is used for chronological ordering and time-based queries.

string format: date-time
<= 29 characters
createdAt

The date and time when this audit log entry was created, recorded in ISO 8601 format. This field is used for implementing data retention policies and automatic cleanup of old audit logs.

string format: date-time
<= 29 characters
expiresAt

The date and time when this audit log entry will be automatically deleted from the system, recorded in ISO 8601 format. This field is used for implementing data retention policies and automatic cleanup of old audit logs.

string format: date-time
<= 29 characters
metadata

Additional context-specific information about the audit event. This flexible object can contain any relevant data that provides more details about the event, such as user information, resource identifiers, or specific parameters of the action. The structure of this object varies depending on the category and type of the audit log.

object
key
additional properties
any
pagination
required

Pagination response.

object
nextCursor

Opaque cursor (base64url-encoded token) for the next page. Null when there are no more items.

string
nullable <= 1024 characters
Example
{
  "auditLogs": [
    {
      "auditLogId": "AUDI-33090c4f-a7b9-48e0-8a2c-79b79d91dff9",
      "category": "flow",
      "type": "step_update",
      "timestamp": "2025-05-12T14:20:31.702Z",
      "expiresAt": "2025-05-19T14:20:31.959Z",
      "metadata": {
        "stepName": "Run script",
        "stepId": "STEP-1d03452e-b664-4d30-96b4-6fe90096ef41",
        "flowId": "PLAY-17a64601-40bb-4304-90f8-08ebf6ae3c19",
        "principalInfo": {
          "name": "Fabrice Delhoste",
          "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
          "id": "USER-c3545882-60b1-709d-1806-d53d80bfaa22",
          "type": "user",
          "email": "john.doe@example.com",
          "ip": "246.157.181.77"
        },
        "flowName": "Exporting logs"
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJsYXN0S2V5IjoiMTIzNCJ9"
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer format: int32
>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining
integer format: int32
<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset
string format: date-time
<= 29 characters

The time at which the current rate limit window resets.

Retry-After
integer format: int32
>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin
string
Allowed values: *

Specifies the allowed origins for CORS.

400

Section titled “400”

The request was invalid. Common causes include:

  • Invalid timestamp format.
  • Using cursor with before or after.
  • Missing limit when using before or after.
  • Invalid field names in the fields parameter.

See the error response for specific details about what went wrong.

Media typeapplication/json
object
type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference
default: about:blank <= 2048 characters
title
required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string
<= 256 characters /^[^\p{C}]+$/
status
required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string
<= 500 characters
instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference
<= 2048 characters
code

Machine-readable error code for bad request / validation failure.

string
Allowed values: BAD_REQUEST
Example
{
  "type": "about:blank",
  "code": "BAD_REQUEST"
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer format: int32
>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining
integer format: int32
<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset
string format: date-time
<= 29 characters

The time at which the current rate limit window resets.

Retry-After
integer format: int32
>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin
string
Allowed values: *

Specifies the allowed origins for CORS.

401

Section titled “401”

Authentication failed. The request lacks valid credentials or the provided credentials are invalid.

Ensure you have:

  • A valid API key or token.
  • Proper authentication headers.
  • Required permissions.
Media typeapplication/json
object
type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference
default: about:blank <= 2048 characters
title
required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string
<= 256 characters /^[^\p{C}]+$/
status
required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string
<= 500 characters
instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference
<= 2048 characters
code

Machine-readable error code for this authentication failure.

string
Allowed values: MISSING_OR_INVALID_TOKEN
Example
{
  "type": "about:blank",
  "code": "MISSING_OR_INVALID_TOKEN"
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer format: int32
>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining
integer format: int32
<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset
string format: date-time
<= 29 characters

The time at which the current rate limit window resets.

Retry-After
integer format: int32
>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin
string
Allowed values: *

Specifies the allowed origins for CORS.

429

Section titled “429”

Too many requests. The request rate limit has been exceeded.

Please wait until the rate limit window resets before making additional requests.

Media typeapplication/json
object
type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference
default: about:blank <= 2048 characters
title
required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string
<= 256 characters /^[^\p{C}]+$/
status
required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string
<= 500 characters
instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference
<= 2048 characters
code

Machine-readable error code for rate limit exceeded.

string
Allowed values: RATE_LIMIT_EXCEEDED
Example
{
  "type": "about:blank",
  "code": "RATE_LIMIT_EXCEEDED"
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer format: int32
>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining
integer format: int32
<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset
string format: date-time
<= 29 characters

The time at which the current rate limit window resets.

Retry-After
integer format: int32
>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin
string
Allowed values: *

Specifies the allowed origins for CORS.

500

Section titled “500”

Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.

Please try again later or contact support if the problem persists.

Media typeapplication/json
object
type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference
default: about:blank <= 2048 characters
title
required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string
<= 256 characters /^[^\p{C}]+$/
status
required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32
>= 100 <= 599
detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string
<= 500 characters
instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference
<= 2048 characters
code

Machine-readable error code for internal server failure.

string
Allowed values: INTERNAL_ERROR
Example
{
  "type": "about:blank",
  "code": "INTERNAL_ERROR"
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer format: int32
>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining
integer format: int32
<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset
string format: date-time
<= 29 characters

The time at which the current rate limit window resets.

Retry-After
integer format: int32
>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin
string
Allowed values: *

Specifies the allowed origins for CORS.