---
title: "Ingest run events"
method: POST
path: "/v1/runs/ingest"
tags: ["Runs"]
---

# Ingest run events

`POST /v1/runs/ingest`

## Request

- Base URL: `https://api.lunary.ai`
- URL: `https://api.lunary.ai/v1/runs/ingest`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/lunary/apis/lunary-api/docs/v1/runs/ingest/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint is for reporting data from platforms not supported by our SDKs.

You can use either your project's Public or Private Key as the Bearer token in the Authorization header.

The expected body is an array of Event objects.

For model calls, you would first track a `start` event with the `input` data.
Once your model call succeeds, you would need to send an `end` event to the API endpoint with the `output` data from the model call.

For a full step-by-step guide on sending LLM data to the Lunary API, see the [Custom Integration](/docs/integrations/custom) guide.

## Request body

- object
  - `events` union
    - Event: Represents an event in the Lunary API for tracking model calls and related operations.
      - `type` 'llm' | 'chain' | 'agent' | 'tool' | 'log' | 'embed' | 'retriever' | 'chat' | 'convo' | 'message' | 'thread': The type of event being reported.
      - `event` string: The specific event name (e.g., "start" or "end").
      - `level` string: The logging level of the event.
      - `runId` string: A unique identifier for the run.
      - `parentRunId` string: The ID of the parent run, if applicable.
      - `timestamp` string, date-time: The time the event occurred.
      - `input` object: The input data for the event, typically in OpenAI chat message format.
      - `tags` string[]: Tags associated with the event.
      - `name` string: The name of the event or model.
      - `output` object: The output data from the event, typically in OpenAI chat message format.
      - `message` union: A message associated with the event.
        - string
        - object
      - `extra` object: Additional data such as temperature, max_tokens, tools, etc.
      - `feedback` object: Feedback data for the event.
      - `templateId` string: The ID of the template used, if applicable.
      - `templateVersionId` string: The version ID of the template used, if applicable.
      - `metadata` object: Additional metadata for the event.
      - `tokensUsage` object
        - `prompt` number: The number of tokens used in the prompt.
        - `completion` number: The number of tokens used in the completion.
      - `error` object
        - `message` string: The error message, if an error occurred.
        - `stack` string: The error stack trace, if available.
      - `appId` string: The ID of the application or project.
    - Event[]
      - `type` 'llm' | 'chain' | 'agent' | 'tool' | 'log' | 'embed' | 'retriever' | 'chat' | 'convo' | 'message' | 'thread': The type of event being reported.
      - `event` string: The specific event name (e.g., "start" or "end").
      - `level` string: The logging level of the event.
      - `runId` string: A unique identifier for the run.
      - `parentRunId` string: The ID of the parent run, if applicable.
      - `timestamp` string, date-time: The time the event occurred.
      - `input` object: The input data for the event, typically in OpenAI chat message format.
      - `tags` string[]: Tags associated with the event.
      - `name` string: The name of the event or model.
      - `output` object: The output data from the event, typically in OpenAI chat message format.
      - `message` union: A message associated with the event.
        - string
        - object
      - `extra` object: Additional data such as temperature, max_tokens, tools, etc.
      - `feedback` object: Feedback data for the event.
      - `templateId` string: The ID of the template used, if applicable.
      - `templateVersionId` string: The version ID of the template used, if applicable.
      - `metadata` object: Additional metadata for the event.
      - `tokensUsage` object
        - `prompt` number: The number of tokens used in the prompt.
        - `completion` number: The number of tokens used in the completion.
      - `error` object
        - `message` string: The error message, if an error occurred.
        - `stack` string: The error stack trace, if available.
      - `appId` string: The ID of the application or project.

## Response `200`

Successful ingestion

- IngestResponse: The response from the ingestion API.
  - `results` object[]
    - `id` string: The ID of the ingested event.
    - `success` boolean: Indicates if the ingestion was successful.
    - `error` string: Error message if the ingestion failed.

## Other responses

- `401`: Project does not exist
- `402`: Incorrect project id format

---

[API](https://skmtc.dev/lunary/apis/lunary-api.md) - [All operations](https://skmtc.dev/lunary/apis/lunary-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lunary/apis/lunary-api/revisions/a38233713bdc?raw)