> ## Documentation Index
> Fetch the complete documentation index at: https://docs.togai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Correct an ingested event
> #### This API lets you to correct events. Available in both synchronous and asynchronous mode
- **Usages**: Reduction of all usages associated with this event
- **Revenue**: Reduction of all revenues associated with this event
- **Entitlements**: Entitlements(Feature Credits) consumed by this event are granted back to the account.
### Possible Actions:
- UNDO: Undo all usages, revenue and entitlements associated with an event
- REDO: Performs UNDO and re-ingests the same event
- REDO_EVENT: Performs UNDO and re-ingests the correction payload of the event
## Query Parameters: Allowed filter combinations
All matching events will be considered for correction
- **Sync mode:** Maximum of first 30 events matching the filters with the default sort order being
**EVENT\_SOURCE\_TIME DESC, EVENT\_ID ASC** can be corrected in a single request.
- **Async mode:** When query parameter **async = true** is given, events matching the filters will be considered for correction and takes place in background. \
Status of background job can be obtained using [List Jobs API](api-reference/jobs/list-jobs)
Unique identifier of the account corresponding to the event
Unique identifier of an event generated by Togai for reference
Identifier of an event provided by the user
Timestamp of an event provided by the user
Timestamp corresponding to the event ingestion time in Togai
Determines the mode of the correction. Defaults to false
`account_id`
`account_id`, `id`
`account_id`, `event_id`
`account_id`, `event_source_time`
`account_id`, `event_id`, `created_at`
`account_id`, `event_id`, `event_source_time`
## OpenAPI
````yaml post /events/correction
openapi: 3.0.3
info:
version: '1.0'
title: Togai Apis
contact:
email: engg@togai.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
description: APIs for Togai App
servers:
- description: Api endpoint
url: https://api.togai.com/
- description: Sandbox api endpoint
url: https://sandbox-api.togai.com/
security:
- bearerAuth: []
tags:
- name: Customers
description: Customer level calls
- name: Accounts
description: Account level calls
- name: Event Schemas
description: Event Schema level calls
- name: Usage Meters
description: Usage Meter level calls
- name: Price Plans
description: (DEPRECATED) Price Plan level calls
- name: PricePlanV2
description: Price Plan V2 level calls
- name: Schedules
description: Account Schedule level calls
- name: Pricing Rules
description: Pricing Rules level calls
- name: Settings
description: Settings
- name: Price Experimentation
description: Price Experimentation apis
- name: InvoiceGroups
description: Invoice Group level calls
- name: Organization
description: Organization level calls
- name: FileStorage
description: File Storage level calls
- name: Aliases
description: Alias level calls
- name: Reports
description: Report level calls
- name: ReportTemplates
description: Report Template level calls
- name: Customer Portal
description: Portal level calls
- name: Alerts
description: Alert level calls
- name: Event Management
description: APIs for getting events ingested in Togai
externalDocs:
description: docs
url: https://togai.com/docs/billing/events
- name: Metrics
description: APIs for getting Togai metrics
externalDocs:
description: docs
url: https://togai.com/docs/metrics
- name: Licenses
description: APIs for getting or updating license records in Togai
- name: Entitlements
description: APIs related to entitlements
- name: Invoices
description: Invoices API
- name: Credits
description: Credits API
- name: Wallet
description: Wallet API
- name: InvoiceTemplates
description: InvoiceTemplates API
- name: InvoiceSequence
description: InvoiceSequence API
- name: Payments
description: Payments API
- name: Authentication
description: Authentication API
externalDocs:
description: Find out more about Togai
url: https://docs.togai.com/docs
paths:
/events/correction:
post:
tags:
- Event Management
summary: Correct an ingested event
description: >
#### This API lets you to correct events. Available in both synchronous
and asynchronous mode
- **Usages**: Reduction of all usages associated with this event
- **Revenue**: Reduction of all revenues associated with this event
- **Entitlements**: Entitlements(Feature Credits) consumed by this event
are granted back to the account.
### Possible Actions:
- UNDO: Undo all usages, revenue and entitlements associated with an
event
- REDO: Performs UNDO and re-ingests the same event
- REDO_EVENT: Performs UNDO and re-ingests the correction payload of the
event
operationId: eventCorrection
parameters:
- $ref: '#/components/parameters/event_correction_action'
- $ref: '#/components/parameters/require_confirmation'
requestBody:
$ref: '#/components/requestBodies/EventCorrectionRequest'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/EventsCorrectionResponse'
examples:
EventsCorrectionResponse:
$ref: '#/components/examples/EventsCorrectionResponse'
'400':
description: Bad request. Please check the response message for failure details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Credential is not valid. Please check the response message for
failure details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Credential does not have access to get events.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: >-
Request throttled. Please check the response message on the failure
details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
parameters:
event_correction_action:
in: query
description: Action to perform in event correction
name: action
required: true
schema:
type: string
enum:
- UNDO
- REDO
- REDO_EVENT
example: UNDO
require_confirmation:
in: query
name: require_confirmation
description: Specifies whether to start a migration only after a confirmation
required: false
schema:
type: boolean
example: false
requestBodies:
EventCorrectionRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/EventCorrectionRequest'
schemas:
EventsCorrectionResponse:
description: Events Correction response
type: object
additionalProperties: false
required:
- data
properties:
data:
type: array
minItems: 1
maxItems: 50
items:
$ref: '#/components/schemas/EventCorrectionInfo'
ErrorResponse:
type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
description: error description
maxLength: 500
EventCorrectionRequest:
description: Event Correction Payload for event correction
type: object
additionalProperties: false
properties:
event:
$ref: '#/components/schemas/Event'
EventCorrectionInfo:
allOf:
- $ref: '#/components/schemas/EventWithStatus'
- type: object
additionalProperties: false
required:
- status
- reason
properties:
status:
type: string
description: Status of the event requested for correction
enum:
- REVERTED
- REVERTED_AND_REINGESTED
- FAILED
reason:
type: string
description: Status description of the event requested for correction
Event:
description: Contents of the event
type: object
additionalProperties: false
required:
- schemaName
- timestamp
- accountId
- attributes
- dimensions
properties:
schemaName:
description: >
Name of the Event Schema.
Know more about [event
schema](https://docs.togai.com/docs/event-schemas)
type: string
minLength: 1
maxLength: 50
id:
description: >-
Togai restricts users to ingest events with same id within a period
of *45 days*. This restriction is common for [/entitled
API](/api-reference/entitlements/ingest-event-if-a-user-is-entitled-to-a-feature),
[/ingest API](/api-reference/event-ingestion/ingest-events-to-togai)
and [/ingestBatch
API](/api-reference/event-ingestion/ingest-events-to-togai-in-batch).
i.e, an id used on /ingest API will not be allowed on /ingestBatch
or /entitled APIs
type: string
maxLength: 512
example: c0b1306d-f506-43a6-856b-69221efaee6b
timestamp:
description: >-
Source time stamp of the event. This timestamp must be in ISO 8601
format.
type: string
format: date-time
example: '2022-06-15T07:30:35.123'
accountId:
description: The event will be associated with the provided account
type: string
maxLength: 512
example: 1
attributes:
description: >-
Attributes are numeric values. It can be usage metric which you push
to Togai
type: array
minItems: 0
maxItems: 10
items:
$ref: '#/components/schemas/Attribute'
dimensions:
$ref: '#/components/schemas/Dimensions'
EventWithStatus:
description: >-
Raw usage event ingested by the business team and the status of the
event ingestion.
type: object
additionalProperties: false
required:
- referenceId
- eventPayload
- ingestionStatus
- createdAt
properties:
referenceId:
type: string
description: Unique id generated by Togai to identify an event uniquely
eventPayload:
$ref: '#/components/schemas/Event'
ingestionStatus:
$ref: '#/components/schemas/IngestionStatus'
customerId:
description: The associated account belongs to this customer
type: string
maxLength: 50
example: '1'
source:
$ref: '#/components/schemas/EventSource'
createdAt:
description: >-
Created time stamp of the event. This timestamp must be in ISO 8601
format.
type: string
format: date-time
example: '2022-06-15T07:30:35.123'
Attribute:
description: Metric to be recorded
type: object
additionalProperties: false
required:
- name
- value
properties:
name:
description: Name of the event attribute
type: string
minLength: 1
maxLength: 50
example: message
value:
description: Value of the event attribute
type: string
pattern: ^-?\d{1,512}(\.\d+)?$
example: 100
unit:
description: >-
Unit with which the attribute value was measured. Natively supported
units - "Meters, Miles, Kilometers, Grams, Kilograms, ounces,
Pounds, Minutes, Hours, Seconds, Milliseconds, Microseconds, None".
Clients are free to add any other custom units.
type: string
minLength: 1
maxLength: 50
example: characters
Dimensions:
description: Dimensions are tags/labels associated with the events.
type: object
additionalProperties:
type: string
minLength: 1
maxLength: 200
example:
Country: India
IngestionStatus:
description: Status about the event ingestion.
type: object
additionalProperties: false
required:
- status
properties:
status:
type: string
description: Ingestion status
enum:
- INGESTION_IN_PROGRESS
- INGESTION_FAILED
- INGESTION_FAILED_SCHEMA_NOT_DEFINED
- INGESTION_FAILED_ENRICHMENT_FAILED
- INGESTION_FAILED_UNITS_INVALID
- INGESTION_COMPLETED_NO_MATCHING_METERS
- INGESTION_COMPLETED_EVENT_METERED
- INGESTION_COMPLETED_EVENT_NOT_METERED
- INGESTION_FAILED_PAST_GRACE_PERIOD
- INGESTION_FAILED_ACCOUNT_NOT_FOUND
- INGESTION_FAILED_DUPLICATE_EVENT
- INGESTION_FAILED_NO_EVENT_ID
- INGESTION_FAILED_INVALID_NAMED_LICENSE_EVENT
- INGESTION_FAILED_INSUFFICIENT_CREDITS
- REVERTED
- UNKNOWN
example: INGESTION_COMPLETED
statusDescription:
type: string
maxLength: 250
example: Ingestion Completed successfully
EventSource:
description: Source of ingestion of event
type: object
additionalProperties: false
required:
- id
- type
properties:
id:
type: string
description: Unique identifier representing the source
maxLength: 100
type:
type: string
description: Type of source
maxLength: 100
examples:
EventsCorrectionResponse:
summary: Example event correction response
value:
data:
- referenceId: event.21OpEx4DHQu.CZlyh
eventPayload:
timestamp: '2023-02-23T14:25:10Z'
schemaName: travelCompletedEvent
id: c0b1306d-f506-43a6-856b-69221efaee6b
accountId: '1'
attributes:
- name: distanceTravelled
value: '50'
unit: Miles
- name: timeSpent
value: '60'
unit: Minutes
dimensions:
location: Seattle
costCenterCode: '1234'
travelType: Business
ingestionStatus:
status: INGESTION_COMPLETED_EVENT_NOT_METERED
statusDescription: >-
Event ingestion completed successfully but the event is not
associated with any bill plan.
customerId: CUS0001
source:
id: ENTITLED
type: ENTITLED
createdAt: '2023-02-23T14:25:10Z'
status: REVERTED
reason: Event Reverted
- referenceId: event.23OrTx4FGQu.XVpzf
eventPayload:
timestamp: '2023-02-23T14:25:10Z'
schemaName: smsSentEvent
id: sdvb325j-f506-43a6-856b-69221efaee6b
accountId: '1'
attributes:
- name: smsCount
value: '50'
unit: count
dimensions: {}
ingestionStatus:
status: INGESTION_COMPLETED_EVENT_NOT_METERED
statusDescription: >-
Event ingestion completed successfully but the event is not
associated with any bill plan.
customerId: CUS0001
source:
id: ''
type: ''
createdAt: '2023-01-01T14:25:10Z'
status: FAILED
reason: Event was ingested in past pricing cycle
responses:
ErrorResponse:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ErrorResponse:
summary: Error message
value:
message:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Bearer
````