Record cache usage events

Records cache usage analytics events. The body of this request is an array of cache usage events.

This endpoint is optional but enables cache hit/miss analytics. Implementers can use this data to track cache effectiveness and optimize storage.

Event types:

HIT: A cached artifact was found and used
MISS: No cached artifact was found for the given hash

Source types:

LOCAL: The cache event was on the user’s local filesystem cache
REMOTE: The cache event is for the remote cache

POST/artifacts/events

Authorization

AuthorizationBearer token · headerrequired

Bearer token authentication. Pass your authentication token in the Authorization header as Bearer <token>.

For self-hosted implementations, the token format and validation logic is up to the implementer. Common approaches include:

Static tokens for simple setups
JWT tokens for stateless authentication
OAuth2 tokens for integration with identity providers

Query parameters

teamIdstring

The team identifier to perform the request on behalf of. Used for multi-tenant cache implementations where artifacts are scoped to teams.

slugstring

The team slug to perform the request on behalf of. Alternative to teamId for identifying the team.

Header parameters

x-artifact-client-cistring

The continuous integration or delivery environment where this artifact operation is being performed. Examples: github-actions, circleci, jenkins.

max length 50

x-artifact-client-interactiveinteger

Indicates whether the client is running in an interactive shell. 1 for interactive, 0 for non-interactive (CI/scripts).

Allowed:01

Request body

requiredapplication/json

Array of CacheEvent

sessionIdstring<uuid>required

A UUID that identifies the Turborepo session that generated this event

sourcestringrequired

The source of the cache event.

LOCAL: The event occurred on the user's local filesystem cache
REMOTE: The event is for the remote cache

Allowed:LOCALREMOTE

eventstringrequired

The type of cache event.

HIT: A cached artifact was found
MISS: No cached artifact was found

Allowed:HITMISS

hashstringrequired

The artifact hash associated with this event

durationinteger

The time taken to generate the artifact in milliseconds. Only meaningful for HIT events.

min 0

Responses

200

Events recorded successfully

400

Bad request. One or more of the provided values in the request query, headers, or body is invalid.

codestringrequired

A machine-readable error code

messagestringrequired

A human-readable error message

401

Unauthorized. The request is missing a valid authentication token or the token is invalid.

codestringrequired

A machine-readable error code

messagestringrequired

A human-readable error message

403

Forbidden. The authenticated user does not have permission to access this resource.

codestringrequired

A machine-readable error code

messagestringrequired

A human-readable error message

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

x-artifact-client-ciheaderThe continuous integration or delivery environment where this artifact operation is being performed. Examples: `github-actions`, `circleci`, `jenkins`.x-artifact-client-interactiveheaderIndicates whether the client is running in an interactive shell. `1` for interactive, `0` for non-interactive (CI/scripts).teamIdqueryThe team identifier to perform the request on behalf of. Used for multi-tenant cache implementations where artifacts are scoped to teams.slugqueryThe team slug to perform the request on behalf of. Alternative to `teamId` for identifying the team.

Bodyapplication/json

Request body

Request

curl -X POST 'https://turborepo-remote-cache.example.workers.dev/v8/artifacts/events' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
    "source": "LOCAL",
    "event": "HIT",
    "hash": "string",
    "duration": 0
  }
]'

const response = await fetch("https://turborepo-remote-cache.example.workers.dev/v8/artifacts/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "[\n  {\n    \"sessionId\": \"f6567dd8-e069-418e-8893-7d22fcf12459\",\n    \"source\": \"LOCAL\",\n    \"event\": \"HIT\",\n    \"hash\": \"string\",\n    \"duration\": 0\n  }\n]"
});

import requests

response = requests.post(
    "https://turborepo-remote-cache.example.workers.dev/v8/artifacts/events",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="[\n  {\n    \"sessionId\": \"f6567dd8-e069-418e-8893-7d22fcf12459\",\n    \"source\": \"LOCAL\",\n    \"event\": \"HIT\",\n    \"hash\": \"string\",\n    \"duration\": 0\n  }\n]",
)

Response

Events recorded successfully

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}