--- title: Create events slug: feature-experimentation/docs/create-events docTags: createdAt: 2026-08-05T20:40:02.000Z --- [Events](docId\:puGm9z4XkEG5PDkyaNmlA) track the success of your experiment by recording specific user actions, such as clicks, pageviews, form submissions, purchases, and scroll depth. To integrate events into your application code using the SDK, see [Track events](docId:3kGIZlCkODJIOJuT3bdWo). ## Create event ### With the Feature Experimentation REST API Use the [Create a custom event](docId\:by3gXKY9ftoLPhu-stYSp) endpoint. **Endpoint** – `POST https://api.optimizely.com/v2/projects/PROJECT_ID/custom_events` **Authentication** – Include your API key in the `Authorization` header as a Bearer token. See [Generate tokens and use the REST APIs](docId\:pQfa5KPTbmy6crey-nsrd). **Request example** ```curl curl --request POST \ --url https://api.optimizely.com/v2/projects/PROJECT_ID/custom_events \ --header 'accept: application/json' \ --header 'authorization: Bearer TOKEN' \ --header 'content-type: application/json' \ --data ' { "archived": false, "description": "Event used to track users that have added the item to the cart.", "key": "add_to_cart" } ' ``` **Response example** ```json { "archived": false, "category": "other", "created": "2025-09-12T16:35:31.697630Z", "description": "Event used to track users that have added the item to the cart.", "event_properties": [], "event_type": "custom", "id": ID, "is_classic": false, "key": "add_to_cart", "name": "add_to_cart", "project_id": PROJECT_ID } ``` See the [Create a custom event](docId\:by3gXKY9ftoLPhu-stYSp) API endpoint reference for the full list of parameters. You can also follow the [REST API cookbook](docId\:hxlniGd5F_X7vj_ttanPB) for additional examples. ### With the Feature Experimentation UI See the [Create event](docId\:BuRedAbq5odrXzImb_plY) section in the user documentation for a step-by-step guide to create events using the UI. ## Add events to your experiments ### With the REST API Use the [Update the Ruleset for a Flag in an Environment](docId\:wpUSoZjCEhG6L1zPVvfhf) endpoint to update your [A/B test](docId:2duP0GL8keJuYvAoQChSU) or [multi-armed bandit optimization](docId\:F5-ZUIoxCu2_XRy26tO-b) with your event. **Endpoint** – `PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset` :::hint{type="warning"} **Important** For `PATCH` requests, first [\`GET the current object\`](docId\:TxxX0KcGkrO_cG331nADs), merge only the fields you need to change, and then send the `PATCH`. This helps prevent overwriting existing settings you did not intend to modify. ::: **Authentication** – Include your API key in the `Authorization` header as a Bearer token. See [Generate tokens and use the REST APIs](docId\:pQfa5KPTbmy6crey-nsrd). **Request example** ```curl curl --request PATCH \ --url "https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/scheduled_changes_flag/environments/development/ruleset" \ --header "Authorization: Bearer TOKEN" \ --header "Content-Type: application/json-patch+json" \ --data '[ { "op": "add", "path": "/rules/a-b-test/metrics/-", "value": { "event_id": EVENT_ID, "event_type": "click", "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "Add to cart clicks" } } ]' ``` **Response example** ```json { "url": "/projects/PROJECT_ID/flags/scheduled_changes_flag/environments/development/ruleset", "update_url": "/projects/PROJECT_ID/flags/scheduled_changes_flag/environments/development/ruleset", "enable_url": "/projects/PROJECT_ID/flags/scheduled_changes_flag/environments/development/ruleset/enabled", "rules": { "a-b-test": { "key": "a-b-test", "name": "a-b-test", "description": "", "variations": { "off": { "key": "off", "name": "Off", "percentage_included": 5000, "variation_id": 1502017, "id": 6688991 }, "on": { "key": "on", "name": "On", "percentage_included": 5000, "variation_id": 1502018, "id": 6688992 } }, "baseline_variation_id": 1502017, "type": "a/b", "distribution_mode": "manual", "id": 1599695, "urn": "rules.flags.optimizely.com::1599695", "archived": false, "enabled": false, "created_time": "2025-09-15T19:52:05.908420Z", "updated_time": "2025-09-15T22:03:43.078372Z", "audience_conditions": [], "audience_ids": [], "percentage_included": 10000, "metrics": [ { "event_id": 30097930171, "event_type": "custom", "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "New event with properties" }, { "event_id": 27189690020, "event_type": "click", "scope": "visitor", "aggregator": "unique", "winning_direction": "increasing", "display_title": "Add to cart clicks" } ], "allow_list": {}, "group_rule": { "group_id": 0, "traffic_allocation": 0 }, "group_remaining_traffic_allocation": 100, "layer_id": 9300001987253, "layer_experiment_id": 9300002732965, "status": "draft" } }, "rule_priorities": [ "a-b-test" ], "id": 1882548, "urn": "rulesets.flags.optimizely.com::1882548", "archived": false, "enabled": false, "updated_time": "2025-09-15T22:03:43.149140Z", "flag_key": "scheduled_changes_flag", "environment_key": "development", "environment_name": "Development", "environment_id": ENVIRONMENT_ID, "default_variation_key": "off", "default_variation_name": "Off", "revision": 4, "status": "draft", "role": "admin" } ``` ### In the Feature Experimentation UI See the [Add events to your experiment](docId\:BuRedAbq5odrXzImb_plY) section in the user documentation for a step-by-step guide. ## Track events in your application code See the track event documentation in your SDK to implement event tracking in your code. - [Android](docId\:kRTOAg7BcKHnsSYIOGsT8) - [C#](docId\:t2cdt_4CYXEkRKj2R_Qx9) - [Flutter](docId:0X4lEtIQOTNKuCjk9kNmn) - [Go](docId\:LcdvFIfZ7GfSxd1M1qb_N) - [Java](docId\:siDJxMQqZQdP3-_90yI3o) - [JavaScript](docId\:m3uU-JFwOjZgWUBjhQfn2) – SDK versions 6.0.0 and later. - [JavaScript (Browser)](docId\:dtQJ11RFUGmfz559B_i18) – SDK versions 5.3.5 and earlier. - [JavaScript (Node)](docId\:QAxkszUJv8lJBPAtkhTH2) – SDK versions 5.3.5 and earlier. - [PHP](docId\:kVuqN1eWmfu_JGnMnXarJ) - [Ruby](docId\:e0Bu1wqkxwIdIw4inzSIC) - [Python](docId:_Z3MmQTkwUR-QgKN8kuMf) - [Swift](docId\:I9jAN0zACRv-CVA3e-jS2) ## Create metrics [Metrics](docId\:e2qGf29S6pO8SW90_IVuH) measure the success of your experiment by telling you whether an experiment is winning, losing, or inconclusive. Metrics are derived from events, which directly track actions like clicks, pageviews, form submissions, purchases, and scroll depth. Optimizely uses a natural-language metrics builder in the UI that lets you define and add metrics to your experiments and campaigns. See [Create a metric in Optimizely using the metric builder](docId\:cphstZe3xKhsY7WsnnLZK) for instructions on creating metrics.