GraphQL API mutation examples

AppSignal’s GraphQL API supports mutations as well as queries. Where a query reads data, a mutation writes it: you can create a custom marker, close an incident, add an uptime monitor, and more. Mutations use the same endpoint and personal API token as queries. Read the GraphQL API page for details on the endpoint and authentication. Most mutations are app-scoped and take an appId argument that scopes the change to a single app. You can find your app ID in your app’s settings screen. Some mutations are organization-scoped and take an organizationSlug argument instead, such as createApp and createStatusPage. This page covers the most common mutations. For the complete, auto-generated list of every mutation and its arguments, see the GraphQL schema reference.

Mutations change data in your account. Test against a non-production app before you automate a mutation against production data.

Incidents

Update an incident

Change an incident’s state, severity, assignees, or notification settings. The number is the incident number shown in AppSignal. state accepts OPEN, WIP, or CLOSED. severity accepts UNTRIAGED, CRITICAL, HIGH, LOW, NONE, or INFORMATIONAL.

mutation UpdateIncident(
  $appId: String!
  $number: Int!
  $state: IncidentStateEnum
  $severity: IncidentSeverityEnum
  $assigneeIds: [String!]
) {
  updateIncident(
    appId: $appId
    number: $number
    state: $state
    severity: $severity
    assigneeIds: $assigneeIds
  ) {
    ... on ExceptionIncident {
      id
      number
      state
      severity
    }
    ... on PerformanceIncident {
      id
      number
      state
      severity
    }
  }
}

{
  "appId": "YOUR-APP-ID",
  "number": 42,
  "state": "CLOSED",
  "severity": "LOW"
}

Bulk update incidents

Update several incidents in one request. Unlike updateIncident, this mutation takes incident IDs rather than incident numbers.

mutation BulkUpdateIncidents(
  $appId: String!
  $ids: [String]!
  $state: IncidentStateEnum
  $severity: IncidentSeverityEnum
) {
  bulkUpdateIncidents(
    appId: $appId
    ids: $ids
    state: $state
    severity: $severity
  ) {
    ... on ExceptionIncident {
      id
      number
      state
    }
    ... on PerformanceIncident {
      id
      number
      state
    }
    ... on AnomalyIncident {
      id
      number
      state
    }
    ... on LogIncident {
      id
      number
      state
    }
  }
}

{
  "appId": "YOUR-APP-ID",
  "ids": ["INCIDENT-ID-1", "INCIDENT-ID-2"],
  "state": "CLOSED"
}

Create a note on an incident

Add a note to an incident’s logbook. The same fields are available on performance, anomaly, and log incidents.

mutation CreateIncidentNote(
  $appId: String!
  $incidentNumber: Int!
  $content: String!
) {
  createIncidentNote(
    appId: $appId
    incidentNumber: $incidentNumber
    content: $content
  ) {
    ... on ExceptionIncident {
      id
      number
      logbook {
        items {
          ... on Note {
            id
            content
            createdAt
          }
        }
      }
    }
  }
}

{
  "appId": "YOUR-APP-ID",
  "incidentNumber": 42,
  "content": "Investigating, deploy reverted."
}

Create an issue from an incident

Create a linked issue in a connected integration. This example uses GitHub; equivalent mutations exist for other integrations: createGitlabIssue, createJiraIssue, createLinearIssue, createShortcutStory, createAsanaTask, and createTrelloCard.

mutation CreateGithubIssue(
  $appId: String!
  $incidentNumber: Int!
  $title: String!
  $description: String!
) {
  createGithubIssue(
    appId: $appId
    incidentNumber: $incidentNumber
    title: $title
    description: $description
  ) {
    ... on ExceptionIncident {
      id
      number
      integrations {
        ... on GitHub {
          name
          issues {
            url
            title
          }
        }
      }
    }
  }
}

{
  "appId": "YOUR-APP-ID",
  "incidentNumber": 42,
  "title": "NoMethodError in OrdersController#create",
  "description": "Tracked in AppSignal incident #42."
}

Remove an integration from an incident

Remove a previously linked integration issue from an incident.

mutation RemoveIntegration(
  $appId: String!
  $incidentNumber: Int!
  $id: String!
) {
  removeIntegration(
    appId: $appId
    incidentNumber: $incidentNumber
    id: $id
  ) {
    ... on ExceptionIncident {
      id
      number
    }
  }
}

{
  "appId": "YOUR-APP-ID",
  "incidentNumber": 42,
  "id": "YOUR-INTEGRATION-ID"
}

Markers

Create or update a custom marker

Create a custom marker to annotate a point in time, such as a configuration change or a manual action. Pass an id to update an existing marker. Omit id to create a new marker.

mutation CreateCustomMarker(
  $appId: String!
  $id: String
  $icon: String!
  $message: String
  $createdAt: DateTime
) {
  createOrUpdateCustomMarker(
    appId: $appId
    id: $id
    icon: $icon
    message: $message
    createdAt: $createdAt
  ) {
    id
    icon
    message
    createdAt
  }
}

{
  "appId": "YOUR-APP-ID",
  "icon": "🚀",
  "message": "Ran database migration"
}

Delete a custom marker

Delete a custom marker by ID.

mutation DeleteCustomMarker($appId: String!, $id: String!) {
  deleteCustomMarker(appId: $appId, id: $id) {
    id
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-MARKER-ID"
}

Alerts and triggers

Create a trigger

Create a metric-based alert trigger. field accepts a value from MetricFieldEnum (such as MEAN, P90, P95, COUNT, GAUGE, or COUNTER). kind is a string describing the trigger type. The GraphQL source docs name ExceptionRate and Throughput as examples. The condition sets the threshold to compare against. To replace an existing trigger, pass its ID as previousTriggerId. comparisonOperator accepts LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN_OR_EQUAL, EQUAL, or NOT_EQUAL.

mutation CreateTrigger(
  $appId: String!
  $previousTriggerId: String
  $name: String
  $metricName: String!
  $kind: String!
  $field: MetricFieldEnum!
  $condition: ThresholdConditionInput!
  $warmupDuration: Int!
  $cooldownDuration: Int!
  $notifierIds: [String!]
) {
  createTrigger(
    appId: $appId
    previousTriggerId: $previousTriggerId
    name: $name
    metricName: $metricName
    kind: $kind
    field: $field
    condition: $condition
    warmupDuration: $warmupDuration
    cooldownDuration: $cooldownDuration
    notifierIds: $notifierIds
  ) {
    id
    name
    metricName
    field
    thresholdCondition {
      value
      comparisonOperator
    }
    warmupDuration
    cooldownDuration
  }
}

{
  "appId": "YOUR-APP-ID",
  "name": "High error rate",
  "metricName": "transaction_exception_count",
  "kind": "ExceptionRate",
  "field": "COUNTER",
  "condition": { "value": 10, "comparisonOperator": "GREATER_THAN" },
  "warmupDuration": 0,
  "cooldownDuration": 5,
  "notifierIds": ["YOUR-NOTIFIER-ID"]
}

Archive a trigger

Archive a trigger so it no longer evaluates metrics or sends alerts.

mutation ArchiveTrigger($appId: String!, $id: String!) {
  archiveTrigger(appId: $appId, id: $id) {
    id
    name
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-TRIGGER-ID"
}

Archive an alert

Archive a single triggered alert. This mutation returns true on success.

mutation ArchiveAlert($appId: String!, $id: String!) {
  archiveAlert(appId: $appId, id: $id)
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-ALERT-ID"
}

Close the last alert for an anomaly incident

Close the most recent open alert for an anomaly incident, identified by its incident number.

mutation EndLastAlert($appId: String!, $number: Int!) {
  endLastAlert(appId: $appId, number: $number) {
    id
    number
    alertState
  }
}

{
  "appId": "YOUR-APP-ID",
  "number": 42
}

Uptime monitors

Create an uptime monitor

Create an uptime monitor from a UptimeMonitorInput. regions accepts one or more of EUROPE, NORTH_AMERICA, ASIA_PACIFIC, or SOUTH_AMERICA.

mutation CreateUptimeMonitor(
  $appId: String!
  $uptimeMonitor: UptimeMonitorInput!
) {
  createUptimeMonitor(appId: $appId, uptimeMonitor: $uptimeMonitor) {
    id
    name
    url
    regions
    warmupDuration
  }
}

{
  "appId": "YOUR-APP-ID",
  "uptimeMonitor": {
    "name": "Marketing site",
    "url": "https://example.com",
    "regions": ["EUROPE", "NORTH_AMERICA"],
    "warmupDuration": 1,
    "notifierIds": ["YOUR-NOTIFIER-ID"]
  }
}

Update an uptime monitor

Update an existing monitor. The uptimeMonitor input takes the same shape as it does when creating one.

mutation UpdateUptimeMonitor(
  $appId: String!
  $id: String!
  $uptimeMonitor: UptimeMonitorInput!
) {
  updateUptimeMonitor(
    appId: $appId
    id: $id
    uptimeMonitor: $uptimeMonitor
  ) {
    id
    name
    url
    regions
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-UPTIME-MONITOR-ID",
  "uptimeMonitor": {
    "name": "Marketing site",
    "url": "https://example.com/health",
    "regions": ["EUROPE"]
  }
}

Delete an uptime monitor

Delete a monitor by ID. This mutation returns the deleted monitor.

mutation DeleteUptimeMonitor($appId: String!, $id: String!) {
  deleteUptimeMonitor(appId: $appId, id: $id) {
    id
    name
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-UPTIME-MONITOR-ID"
}

Check-ins

Create a check-in trigger

Create a cron or heartbeat check-in trigger. kind accepts CRON or HEARTBEAT. For a cron trigger, set syntax to the cron expression. Use UTC for timezone where possible.

mutation CreateCheckInTrigger(
  $appId: String!
  $identifier: String!
  $kind: CheckInTriggerKindEnum!
  $waitTimeMinutes: Int!
  $syntax: String
  $timezone: String
  $notifierIds: [String!]
) {
  createCheckInTrigger(
    appId: $appId
    identifier: $identifier
    kind: $kind
    waitTimeMinutes: $waitTimeMinutes
    syntax: $syntax
    timezone: $timezone
    notifierIds: $notifierIds
  ) {
    id
    identifier
    kind
    syntax
    timezone
    waitTimeMinutes
  }
}

{
  "appId": "YOUR-APP-ID",
  "identifier": "nightly-backup",
  "kind": "CRON",
  "syntax": "0 2 * * *",
  "timezone": "UTC",
  "waitTimeMinutes": 5,
  "notifierIds": ["YOUR-NOTIFIER-ID"]
}

Update a check-in trigger

Update an existing check-in trigger. Only the fields you pass are changed.

mutation UpdateCheckInTrigger(
  $appId: String!
  $id: String!
  $syntax: String
  $waitTimeMinutes: Int
  $notifierIds: [String!]
) {
  updateCheckInTrigger(
    appId: $appId
    id: $id
    syntax: $syntax
    waitTimeMinutes: $waitTimeMinutes
    notifierIds: $notifierIds
  ) {
    id
    identifier
    syntax
    waitTimeMinutes
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-CHECK-IN-TRIGGER-ID",
  "syntax": "0 3 * * *",
  "waitTimeMinutes": 10
}

Delete a check-in trigger

Delete a check-in trigger by ID.

mutation DeleteCheckInTrigger($appId: String!, $id: String!) {
  deleteCheckInTrigger(appId: $appId, id: $id) {
    id
    identifier
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-CHECK-IN-TRIGGER-ID"
}

Dashboards

Create a dashboard

Create an empty dashboard. Add visuals to it with the createVisualTimeseries and createVisualNumber mutations, or import a complete dashboard with importDashboard. Dashboard visuals are also managed through createVisualTimeseries, createVisualNumber, updateVisualTimeseries, updateVisualNumber, updateVisualLayouts, and deleteVisual. To create a standalone saved visual for later retrieval through the saved visuals REST endpoints, use createSavedVisual.

mutation CreateDashboard(
  $appId: String!
  $title: String!
  $description: String
) {
  createDashboard(appId: $appId, title: $title, description: $description) {
    id
    title
    description
  }
}

{
  "appId": "YOUR-APP-ID",
  "title": "Background jobs",
  "description": "Throughput and queue time for worker jobs."
}

Update a dashboard

Update a dashboard’s title or description. The title is required.

mutation UpdateDashboard(
  $appId: String!
  $id: String!
  $title: String!
  $description: String
) {
  updateDashboard(
    appId: $appId
    id: $id
    title: $title
    description: $description
  ) {
    id
    title
    description
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-DASHBOARD-ID",
  "title": "Background jobs",
  "description": "Updated description."
}

Delete a dashboard

Delete a dashboard by ID.

mutation DeleteDashboard($appId: String!, $id: String!) {
  deleteDashboard(appId: $appId, id: $id) {
    id
    title
  }
}

{
  "appId": "YOUR-APP-ID",
  "id": "YOUR-DASHBOARD-ID"
}

Import a dashboard

Import a dashboard from a JSON definition. The json argument is a JSON-encoded string, so escape it when sending it as a variable.

mutation ImportDashboard($appId: String!, $json: String!) {
  importDashboard(appId: $appId, json: $json) {
    id
    title
  }
}

{
  "appId": "YOUR-APP-ID",
  "json": "{\"title\":\"Imported dashboard\",\"visuals\":[]}"
}

Logs

Create a log trigger

Create a trigger that opens an incident when log lines match a query. severities accepts log severity names such as error, warn, or info.

mutation CreateLogTrigger(
  $appId: String!
  $name: String!
  $query: String!
  $sourceIds: [String!]
  $severities: [String!]
  $notifierIds: [String!]
) {
  createLogTrigger(
    appId: $appId
    name: $name
    query: $query
    sourceIds: $sourceIds
    severities: $severities
    notifierIds: $notifierIds
  ) {
    id
    name
    query
    severities
  }
}

{
  "appId": "YOUR-APP-ID",
  "name": "Payment errors",
  "query": "payment failed",
  "severities": ["error"],
  "notifierIds": ["YOUR-NOTIFIER-ID"]
}

Logs are also managed through GraphQL beyond triggers. Use createLogSource, updateLogSource, and deleteLogSource for sources; createLogView, updateLogView, and deleteLogView for saved views; createLogLineAction, updateLogLineAction, deleteLogLineAction, and reorderLogLineActions for ingestion rules; updateLogTrigger and deleteLogTrigger for log triggers; and createLogExport, updateLogExport, and deleteLogExport for S3 exports.

Organization-scoped mutations

Some mutations act on an organization rather than a single app, so they take an organizationSlug argument instead of appId. You can find the slug in the URL of your organization in AppSignal.

Create an app

Create a new app within an organization.

mutation CreateApp(
  $organizationSlug: String!
  $name: String!
  $environment: String!
) {
  createApp(
    organizationSlug: $organizationSlug
    name: $name
    environment: $environment
  ) {
    id
    name
    environment
  }
}

{
  "organizationSlug": "YOUR-ORGANIZATION-SLUG",
  "name": "My app",
  "environment": "production"
}

Create a status page

Create a public status page from a CreateStatusPageInput. title and hostname are required.

mutation CreateStatusPage(
  $organizationSlug: String!
  $statusPage: CreateStatusPageInput!
) {
  createStatusPage(
    organizationSlug: $organizationSlug
    statusPage: $statusPage
  ) {
    id
    title
    hostname
    state
  }
}

{
  "organizationSlug": "YOUR-ORGANIZATION-SLUG",
  "statusPage": {
    "title": "Service status",
    "hostname": "status.example.com",
    "uptimeMonitorIds": ["YOUR-UPTIME-MONITOR-ID"],
    "threshold": 1
  }
}

Status pages also support createStatusPageUpdate, updateStatusPage, updateStatusPageUpdate, deleteStatusPage, and deleteStatusPageUpdate. For CSV exports, use createCsvExport to start an export and createCsvExportUrl to generate a download URL for a completed export.

More mutations

These examples cover the most common operations. The API includes more, grouped in the schema reference under Core (app and hosted collector management), Dashboards (visuals and layouts), Logs (sources, views, and exports), Exports (CSV), Status pages (updates), and User preferences. For the full list of mutations and their arguments, see the GraphQL schema reference.

AppSignal API

MCP server

AppSignal CLI

Incidents

Update an incident

Bulk update incidents

Create a note on an incident

Create an issue from an incident

Remove an integration from an incident

Markers

Create or update a custom marker

Delete a custom marker

Alerts and triggers

Create a trigger

Archive a trigger

Archive an alert

Close the last alert for an anomaly incident

Uptime monitors

Create an uptime monitor

Update an uptime monitor

Delete an uptime monitor

Check-ins

Create a check-in trigger

Update a check-in trigger

Delete a check-in trigger

Dashboards

Create a dashboard

Update a dashboard

Delete a dashboard

Import a dashboard

Logs

Create a log trigger

Organization-scoped mutations

Create an app

Create a status page

More mutations

​Incidents

​Update an incident

​Bulk update incidents

​Create a note on an incident

​Create an issue from an incident

​Remove an integration from an incident

​Markers

​Create or update a custom marker

​Delete a custom marker

​Alerts and triggers

​Create a trigger

​Archive a trigger

​Archive an alert

​Close the last alert for an anomaly incident

​Uptime monitors

​Create an uptime monitor

​Update an uptime monitor

​Delete an uptime monitor

​Check-ins

​Create a check-in trigger

​Update a check-in trigger

​Delete a check-in trigger

​Dashboards

​Create a dashboard

​Update a dashboard

​Delete a dashboard

​Import a dashboard

​Logs

​Create a log trigger

​Organization-scoped mutations

​Create an app

​Create a status page

​More mutations

Incidents

Update an incident

Bulk update incidents

Create a note on an incident

Create an issue from an incident

Remove an integration from an incident

Markers

Create or update a custom marker

Delete a custom marker

Alerts and triggers

Create a trigger

Archive a trigger

Archive an alert

Close the last alert for an anomaly incident

Uptime monitors

Create an uptime monitor

Update an uptime monitor

Delete an uptime monitor

Check-ins

Create a check-in trigger

Update a check-in trigger

Delete a check-in trigger

Dashboards

Create a dashboard

Update a dashboard

Delete a dashboard

Import a dashboard

Logs

Create a log trigger

Organization-scoped mutations

Create an app

Create a status page

More mutations