Using the Audit Log

• Audit Logs are available only to Admin users.
• Logs can be exported in CSV or JSON format.
• Export audit logs from the LinearB UI or through the LinearB API.
• Filter exports by a specific date range and, when using the API, optionally by team.
• Each log entry includes who acted, what changed, when it happened, and whether the action was user- or system-initiated.
• Every tool call made through the LinearB MCP Server is recorded under the mcp category, including who made the call, which tool ran, and how much data it returned.

Admin access is required. Only users with Admin permissions can view and generate audit logs.

1. Sign in to LinearB using an Admin account.
2. Open Company Settings.
3. Click Settings in the lower-left corner.
4. Navigate to the General tab.
5. Scroll to the bottom to find the Audit Log section.

1. Select a time frame
   • Use the date picker to choose a start and end date.
   • Example: Past 30 days (Oct 4 – Nov 3).
2. Choose a file format
   • CSV – Suitable for Excel or Google Sheets.
   • JSON – Best for developers or system ingestion.
3. Download the log
   • Click Download Log.
   • The file is generated and saved locally.
   • Larger date ranges may take longer to process.

You can export the same organization audit log available in the LinearB UI using the LinearB API. This is useful for automated reporting, security workflows, compliance processes, and integrations with external systems.

Use the following endpoint:

GET /api/v2/audit-log/export

Request Parameters

Response

A successful request returns a presigned URL that you can use to download the generated audit log file.

{
            "url": "https://..."
          }

For authentication requirements, response codes, and the complete endpoint specification, see the LinearB Audit Log API reference .

• organization_id – Unique identifier of your organization
• team_id – Team associated with the action
• account_id – User who performed the action
• repository_id – Repository affected
• created_at – Timestamp of the action
• category – High-level action category (e.g., Authentication, mcp)
• sub_category – Specific event type (e.g., Login)
• description – Short explanation of the event
• type – Source of the action
  • User – Performed by a person
  • System – Triggered automatically by LinearB
• metadata – Key-value pairs describing what changed
  • Example: {"workingDays":{"oldValue":"1-6","newValue":"1-5"}}

When your team connects an AI assistant to LinearB through the MCP Server (Model Context Protocol), each tool call the assistant makes is written to your organization's audit log. Use these entries to see which users queried LinearB data through MCP, which tools they used, and how much data each call returned.

What is recorded

Each MCP tool call creates one audit log entry with:

• category – Always mcp.
• account_id – The user who made the call. See How calls are attributed below.
• description – A short summary of the call, including the tool name and the number of items returned.
• metadata – Details about the call:
  • Tool name
  • Names of the arguments passed to the tool (argument values are not stored)
  • Authentication method: OAuth or API token (for API tokens, the token prefix only)
  • Number of items returned and response size
  • Whether the response exceeded the MCP Server size limit
  • Outcome (success or error), HTTP status, and duration
  • The MCP client used to make the call

How calls are attributed

• OAuth – The entry is attributed to the user who signed in to the MCP Server.
• API token – The entry is attributed to the user who owns the API token, which may not be the person who made the call. Use the token prefix in metadata to identify which token was used.

Filtering and Analysis

• Filter by user, team, category, or action type.
• Use spreadsheet tools (CSV) or parsers (JSON) for analysis.

Monitoring and Security

• Review metadata to understand configuration changes.
• Monitor System actions to verify automations.
• Scan logs regularly for unusual or unauthorized activity.
• Filter on the mcp category to review AI assistant access to LinearB data, and look for unexpected users, tools, or unusually large responses.

Storage and Compliance

• Store audit logs securely with restricted access.
• Encrypt files if they contain sensitive data.
• Ensure handling aligns with your compliance requirements.

Cannot access audit logs

• Confirm you are logged in as an Admin.
• Verify you are viewing Company Settings.
• If issues persist, contact LinearB Support.

Slow generation or download

• Large date ranges take longer to process.
• Try exporting a shorter time window.

File format issues

• Use Excel or Google Sheets for CSV files.
• Use a JSON viewer or text editor for JSON files.

MCP tool calls are missing from the log

• Only tool calls that reach the LinearB MCP Server are recorded. Requests rejected before reaching the server, for example by network security rules, do not appear.
• Calls made with an API token appear under the token owner's account, not the caller's.