Skip to main content
GET
/
v1
/
events
/
by-key
Get event by idempotency key
curl --request GET \
  --url https://api.scrip.dev/v1/events/by-key \
  --header 'X-API-Key: <api-key>'
import requests

url = "https://api.scrip.dev/v1/events/by-key"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.scrip.dev/v1/events/by-key', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.scrip.dev/v1/events/by-key",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.scrip.dev/v1/events/by-key"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.scrip.dev/v1/events/by-key")
  .header("X-API-Key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/events/by-key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "created_at": "2024-01-15T10:30:00Z",
  "error_code": "program_not_found",
  "error_message": "rule condition evaluation failed",
  "event_data": {},
  "event_timestamp": "2024-01-15T10:30:00Z",
  "event_type": "EXTERNAL",
  "external_id": "user_abc123",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "order-12345-completed",
  "participant_id": "550e8400-e29b-41d4-a716-446655440002",
  "processed_at": "2024-01-15T10:30:02Z",
  "program_id": "550e8400-e29b-41d4-a716-446655440001",
  "received_at": "2024-01-15T10:30:01Z",
  "recipient_id": "550e8400-e29b-41d4-a716-446655440003",
  "rule_evaluations": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "error_message": "condition evaluation failed",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "OUTSIDE_TIME_WINDOW",
      "rule_history_id": "550e8400-e29b-41d4-a716-446655440003",
      "rule_id": "550e8400-e29b-41d4-a716-446655440001",
      "rule_name": "Welcome Bonus",
      "status": "SUCCESS",
      "stopped_by_rule_id": "550e8400-e29b-41d4-a716-446655440002"
    }
  ],
  "status": "COMPLETED",
  "updated_at": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Invalid request parameters"
}
{
  "code": "unauthorized",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Missing or invalid credentials"
}
{
  "code": "forbidden",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Insufficient permissions for this action"
}
{
  "code": "not_found",
  "details": {
    "expected": "uuid",
    "field": "asset_id",
    "fields": [
      {
        "expected": "<unknown>",
        "field": "amount",
        "message": "This field is required",
        "reason": "required",
        "received": "-10.00"
      }
    ],
    "reason": "invalid",
    "received": "not-a-uuid"
  },
  "message": "Resource not found"
}
{
  "code": "internal_error",
  "message": "An internal error occurred"
}
Looks up an event by its idempotency_key and program_id. Both are required as query parameters because idempotency keys are scoped per program. This is the preferred lookup method when you have the key you used at ingestion time but not the event ID. It reads the same store and returns the same event object as the get-by-ID endpoint, including processing status and rule evaluation results. It is subject to the same brief post-accept visibility window: a freshly accepted event may 404 here until the async consumer materializes it. Poll until it resolves. An event that was rejected during async processing resolves as status FAILED with an error_code, not as a 404. Pass include_skipped=true to include rule evaluations with SKIPPED_ERROR or SKIPPED_TIMEOUT status.
For usage patterns and examples, see the Event Processing guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Query Parameters

​
program_id
string<uuid>
required

Program ID

​
idempotency_key
string
required

Idempotency key

​
include_skipped
boolean
default:false

Include skipped rule evaluations (SKIPPED_ERROR, SKIPPED_TIMEOUT)

Response

Event details with rule executions

​
created_at
string<date-time>

When this event was created

Example:

"2024-01-15T10:30:00Z"

​
error_code
string

Machine-readable failure code for a terminal FAILED event, when one is available (e.g. program_not_found, participant_suspended, participant_inactive). NULL when the event did not fail or the failure carried no stable code.

Example:

"program_not_found"

​
error_message
string

Error details if the event failed during processing

Example:

"rule condition evaluation failed"

​
event_data
object

Original event data payload

​
event_timestamp
string<date-time>

When the event occurred (from the ingestion request)

Example:

"2024-01-15T10:30:00Z"

​
event_type
string

Event type: EXTERNAL (API-ingested) or SYSTEM (internally generated)

Example:

"EXTERNAL"

​
external_id
string

Your system's identifier for the participant (the value provided at ingestion)

Example:

"user_abc123"

​
id
string<uuid>

Unique identifier for this event

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
idempotency_key
string

Client-provided unique key for deduplication

Example:

"order-12345-completed"

​
participant_id
string<uuid>

Participant UUID, resolved from external_id if one was provided at ingestion

Example:

"550e8400-e29b-41d4-a716-446655440002"

​
processed_at
string<date-time>

When the event finished processing (null while pending or processing)

Example:

"2024-01-15T10:30:02Z"

​
program_id
string<uuid>

Program this event belongs to

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
received_at
string<date-time>

When Scrip received the event

Example:

"2024-01-15T10:30:01Z"

​
recipient_id
string<uuid>

Reward recipient UUID, if different from the triggering participant

Example:

"550e8400-e29b-41d4-a716-446655440003"

​
rule_evaluations
object[]

RuleEvaluations lists all rules that were evaluated for this event and their outcomes

​
status
string

Processing status: RECEIVED, PENDING, PROCESSING, COMPLETED, or FAILED

Example:

"COMPLETED"

​
updated_at
string<date-time>

When this event was last updated

Example:

"2024-01-15T10:30:00Z"