• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHub
Download
Try Terraform Cloud

    Terraform Cloud

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Assessment Results
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Drift Detection
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»VCS Events API

Note: The VCS Events API is still in beta as support is being added for additional VCS providers. Currently only GitLab.com connections established after December 2020 are supported.

VCS (version control system) events describe changes within your organization for VCS-related actions. Events are only stored for 10 days. If information about the OAuth Client or OAuth Token are available at the time of the event, it will be logged with the event.

»List VCS events

This endpoint lists VCS events for an organization

GET /organizations/:organization_name/vcs-events

ParameterDescription
:organization_nameThe name of the organization to list VCS events from. The organization must already exist in the system and the user must have permissions to manage VCS settings.

Note: Viewing VCS events is restricted to the owners team, teams with the "Manage VCS Settings", and the organization API token. (More about permissions.)

»Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 workspaces per page.
filter[from]Optional. Must be RFC3339 formatted and in UTC. If omitted, the endpoint will default to 10 days ago.
filter[to]Optional. Must be RFC3339 formatted and in UTC. If omitted, the endpoint will default to now.
filter[oauth_client_external_ids]Optional. Format as a comma-separated string. If omitted, the endpoint will return all events.
filter[levels]Optional. info and error are the only accepted values. If omitted, the endpoint will return both info and error events.
includeOptional. Allows including related resource data. This endpoint only supports oauth_client as a value. Only the name, service-provider, and id will be returned on the OAuth Client object in the included block.

»Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z&filter%5Bto%5D=2021-02-12T14%3A09%3A59Z&filter%5Boauth_client_external_ids%5D=oc-hhTM7WNUUgbXJpkW&filter%5Blevels%5D=info&include=oauth_client
$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z&filter%5Bto%5D=2021-02-12T14%3A09%3A59Z&filter%5Boauth_client_external_ids%5D=oc-hhTM7WNUUgbXJpkW&filter%5Blevels%5D=info&include=oauth_client

»Sample Response

{
  "data": [
    {
      "id": "ve-DJpbEwZc98ZedHZG",
      "type": "vcs-events",
      "attributes": {
        "created-at": "2021-02-09 20:07:49.686182 +0000 UTC",
        "level": "info",
        "message": "Loaded 11 repositories",
        "organization-id": "org-SBVreZxVessAmCZG"
      },
      "relationships": {
        "oauth-client": {
          "data": {
            "id": "oc-LePsVhHXhCM6jWf3",
            "type": "oauth-clients"
          },
          "links": {
            "related": "/api/v2/oauth-clients/oc-LePsVhHXhCM6jWf3"
          }
        },
        "oauth-token": {
          "data": {
            "id": "ot-Ma2cs8tzjv3LYZHw",
            "type": "oauth-tokens"
          },
          "links": {
            "related": "/api/v2/oauth-tokens/ot-Ma2cs8tzjv3LYZHw"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "oc-LePsVhHXhCM6jWf3",
      "type": "oauth-clients",
      "attributes": {
        "name": "working",
        "service-provider": "gitlab_hosted"
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          },
          "links": {
            "related": "/api/v2/organizations/my-organization"
          }
        },
        "oauth-tokens": {
          "data": [
            {
              "id": "ot-Ma2cs8tzjv3LYZHw",
              "type": "oauth-tokens"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 8
    }
  }
}
{
  "data": [
    {
      "id": "ve-DJpbEwZc98ZedHZG",
      "type": "vcs-events",
      "attributes": {
        "created-at": "2021-02-09 20:07:49.686182 +0000 UTC",
        "level": "info",
        "message": "Loaded 11 repositories",
        "organization-id": "org-SBVreZxVessAmCZG"
      },
      "relationships": {
        "oauth-client": {
          "data": {
            "id": "oc-LePsVhHXhCM6jWf3",
            "type": "oauth-clients"
          },
          "links": {
            "related": "/api/v2/oauth-clients/oc-LePsVhHXhCM6jWf3"
          }
        },
        "oauth-token": {
          "data": {
            "id": "ot-Ma2cs8tzjv3LYZHw",
            "type": "oauth-tokens"
          },
          "links": {
            "related": "/api/v2/oauth-tokens/ot-Ma2cs8tzjv3LYZHw"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "oc-LePsVhHXhCM6jWf3",
      "type": "oauth-clients",
      "attributes": {
        "name": "working",
        "service-provider": "gitlab_hosted"
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          },
          "links": {
            "related": "/api/v2/organizations/my-organization"
          }
        },
        "oauth-tokens": {
          "data": [
            {
              "id": "ot-Ma2cs8tzjv3LYZHw",
              "type": "oauth-tokens"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 8
    }
  }
}
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager