Skip to content
Vercel
Remote Cache API

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

bearerToken
AuthorizationBearer <token>

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

In: header

Query Parameters

teamId?string

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

slug?string

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

Header Parameters

x-artifact-client-ci?string

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

Lengthlength <= 50
x-artifact-client-interactive?integer

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

Value in0 | 1

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://localhost:3000/artifacts/events" \  -H "Content-Type: application/json" \  -d '[    {      "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",      "source": "LOCAL",      "event": "HIT",      "hash": "string"    }  ]'
Empty
{
  "code": "string",
  "message": "string"
}
{
  "code": "string",
  "message": "string"
}
{
  "code": "string",
  "message": "string"
}