---
updatedAt: 2026-06-02T20:18:10.000Z
agentTools:
  projectIndex: https://developers.tetrascience.com/llms.txt
---

# Agent Status (Heart Beat)

This endpoint allows TetraScience Agent to send heartbeats to the Tetrascience platform periodically. Platform will return the agent's name. It's recommended to send a heartbeat every 30 seconds.

It requires a user-defined agent set up in the TetraScience Web UI.

Required fields:
- agentId
- agentVersion

Optional fields:
- agent
- sourceType - If agent defines various source types, like file-log agent, this should be an array of objects with `filePath` and `type` values. Otherwise, it should be single item array that contains object with field `type`

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Agents",
    "version": "4.3.0"
  },
  "servers": [
    {
      "url": "https://api.tetrascience.com",
      "description": "Production Server"
    },
    {
      "url": "https://api.tetrascience-uat.com",
      "description": "User Acceptance Server"
    },
    {
      "url": "https://api.tetrascience-dev.com",
      "description": "Development Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "token": {
        "type": "apiKey",
        "description": "JWT Token for authentication",
        "in": "header",
        "name": "ts-auth-token"
      },
      "orgSlug": {
        "type": "apiKey",
        "description": "Your organization slug",
        "in": "header",
        "name": "x-org-slug"
      }
    }
  },
  "security": [
    {
      "token": [],
      "orgSlug": []
    }
  ],
  "paths": {
    "/v1/data-acquisition/agent/status": {
      "post": {
        "summary": "Agent Status (Heart Beat)",
        "description": "This endpoint allows TetraScience Agent to send heartbeats to the Tetrascience platform periodically. Platform will return the agent's name. It's recommended to send a heartbeat every 30 seconds.\n\nIt requires a user-defined agent set up in the TetraScience Web UI.\n\nRequired fields:\n- agentId\n- agentVersion\n\nOptional fields:\n- agent\n- sourceType - If agent defines various source types, like file-log agent, this should be an array of objects with `filePath` and `type` values. Otherwise, it should be single item array that contains object with field `type`",
        "tags": [
          "Data Acquisition"
        ],
        "operationId": "user-defined-integration-agent-status-heart-beat",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agentId",
                  "agentVersion"
                ],
                "properties": {
                  "agentId": {
                    "type": "string",
                    "description": "This is the sourceId for a user-defined integration. Need to copy from the TDP web UI, where the user-defined integration is created. For existing Tetra Agent that can connect to TetraScience Cloud directly, provide the agentId to this field."
                  },
                  "agentVersion": {
                    "type": "string",
                    "description": "The Agent version, such as \"v1.0.0\"."
                  },
                  "agent": {
                    "type": "string",
                    "description": "Type of agent, in the form `TetraScience.Agent.file-log`, `TetraScience.Agent.empower`, etc. If provided, object in data lake will have the metadata value `agent` in the form of `agent agentVersion` (for example, `TetraScience.Agent.file-log v4.3.0')",
                    "enum": [
                      "TetraScience.Agent.file-log",
                      "TetraScience.Agent.empower",
                      "TetraScience.Agent.unicorn",
                      "TetraScience.Agent.labx",
                      "TetraScience.Agent.chromeleon",
                      "TetraScience.Agent.user-defined"
                    ],
                    "default": "TetraScience.Agent.user-defined"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"agentName\": \"test\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "agentName": {
                      "type": "string",
                      "example": "test"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"statusCode\": 404,\n    \"error\": \"Not Found\",\n    \"message\": \"Source with source ID 47ab98d5-cccb-4a7d-86f4-0ff8f7c11bda does not exist\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "statusCode": {
                      "type": "integer",
                      "example": 404,
                      "default": 0
                    },
                    "error": {
                      "type": "string",
                      "example": "Not Found"
                    },
                    "message": {
                      "type": "string",
                      "example": "Source with source ID 47ab98d5-cccb-4a7d-86f4-0ff8f7c11bda does not exist"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "x-readme-fauxas": true
}
```