> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Dashboard Interactions

> Retrieve detailed conversation-level data for granular analysis and reporting

Returns comprehensive conversation data including user details, agent information, usage metrics, and tool invocations.

## Authentication

This endpoint requires a valid JWT token from Clerk authentication. The token must include organization membership.

## Query Parameters

<ParamField query="from" type="string" required>
  Start date for the query range (ISO 8601 format, e.g., "2024-01-01T00:00:00.000Z")
</ParamField>

<ParamField query="to" type="string" required>
  End date for the query range (ISO 8601 format, e.g., "2024-12-31T23:59:59.999Z")
</ParamField>

<ParamField query="allInOrg" type="boolean" default="false">
  Whether to include conversations for all users in the organization. Requires `org:admin` role.
</ParamField>

<ParamField query="userId" type="string">
  Filter results to a specific user ID (admin only when `allInOrg` is true)
</ParamField>

<ParamField query="metadataKey" type="string">
  Filter by a specific metadata key in user's organization-scoped metadata
</ParamField>

<ParamField query="metadataValue" type="string">
  Filter by a specific metadata value. Can be used with or without metadataKey. Only searches within the current organization.
</ParamField>

## Response

Returns an array of conversation objects, organized hierarchically with sub-conversations nested under their parent conversations.

<ResponseField name="id" type="string">
  Unique conversation identifier
</ResponseField>

<ResponseField name="agentId" type="number">
  ID of the agent used in this conversation
</ResponseField>

<ResponseField name="upstreamConversationId" type="string" nullable>
  Parent conversation ID if this is a sub-conversation
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when conversation was created
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when conversation was last updated
</ResponseField>

<ResponseField name="agentName" type="string">
  Display name of the agent
</ResponseField>

<ResponseField name="agentModel" type="string">
  AI model used by the agent (e.g., "gpt-4", "claude-3-sonnet")
</ResponseField>

<ResponseField name="agentLogoUrl" type="string" nullable>
  URL to the agent's logo/avatar image
</ResponseField>

<ResponseField name="userId" type="string">
  Clerk user ID of the conversation participant
</ResponseField>

<ResponseField name="userEmail" type="string">
  Email address of the user
</ResponseField>

<ResponseField name="userFirstName" type="string" nullable>
  User's first name
</ResponseField>

<ResponseField name="userLastName" type="string" nullable>
  User's last name
</ResponseField>

<ResponseField name="userPublicMetadata" type="object">
  Organization-scoped user metadata (isolated per organization)
</ResponseField>

<ResponseField name="firstMessageText" type="string" nullable>
  Text content of the first message in the conversation
</ResponseField>

<ResponseField name="userMessageCount" type="number">
  Number of messages sent by the user
</ResponseField>

<ResponseField name="assistantMessageCount" type="number">
  Number of messages sent by the assistant
</ResponseField>

<ResponseField name="totalMessageCount" type="number">
  Total number of messages in the conversation
</ResponseField>

<ResponseField name="duration" type="number" nullable>
  Conversation duration in seconds
</ResponseField>

<ResponseField name="totalTokens" type="number">
  Total token usage for this conversation
</ResponseField>

<ResponseField name="inputTokens" type="number">
  Input tokens (user messages and system prompts) for this conversation
</ResponseField>

<ResponseField name="outputTokens" type="number">
  Output tokens (assistant responses) for this conversation
</ResponseField>

<ResponseField name="attachmentCount" type="number">
  Number of file attachments in the conversation
</ResponseField>

<ResponseField name="toolCalls" type="array">
  Array of all tool invocations made during the conversation

  <Expandable title="Tool Call Object">
    <ResponseField name="toolName" type="string">
      Name of the tool that was invoked
    </ResponseField>

    <ResponseField name="args" type="object">
      Arguments passed to the tool
    </ResponseField>

    <ResponseField name="result" type="any">
      Result returned by the tool
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lastFinishReason" type="string" nullable>
  Reason the last message generation finished (e.g., "stop", "length", "tool\_calls")
</ResponseField>

<ResponseField name="totalFeedback" type="number" nullable>
  Total number of feedback responses for this conversation
</ResponseField>

<ResponseField name="totalHelpful" type="number" nullable>
  Number of positive feedback responses
</ResponseField>

<ResponseField name="totalNotHelpful" type="number" nullable>
  Number of negative feedback responses
</ResponseField>

<ResponseField name="feedbackData" type="array" nullable>
  Detailed feedback data with timestamps and comments
</ResponseField>

<ResponseField name="subConversations" type="array">
  Array of nested sub-conversations (same structure as parent)
</ResponseField>

### Examples

<CodeGroup>
  ```curl Basic Request theme={null}
  curl -X GET "https://asteragents.com/api/dashboard/getInteractions?from=2024-01-01T00:00:00.000Z&to=2024-12-31T23:59:59.999Z&allInOrg=true" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN"
  ```

  ```curl With Metadata Filter theme={null}
  curl -X GET "https://asteragents.com/api/dashboard/getInteractions?from=2024-01-01T00:00:00.000Z&to=2024-12-31T23:59:59.999Z&metadataKey=department&metadataValue=engineering" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN"
  ```

  ```javascript theme={null}
  const response = await fetch('/api/dashboard/getInteractions?' + new URLSearchParams({
    from: '2024-01-01T00:00:00.000Z',
    to: '2024-12-31T23:59:59.999Z',
    allInOrg: 'true',
    metadataKey: 'department',
    metadataValue: 'engineering'
  }), {
    headers: {
      'Authorization': 'Bearer ' + token
    }
  });

  const interactions = await response.json();
  ```

  ```python theme={null}
  import requests

  response = requests.get(
      'https://asteragents.com/api/dashboard/getInteractions',
      params={
          'from': '2024-01-01T00:00:00.000Z',
          'to': '2024-12-31T23:59:59.999Z',
          'allInOrg': 'true',
          'userId': 'user_2ABC123DEF'
      },
      headers={'Authorization': f'Bearer {token}'}
  )

  interactions = response.json()
  ```

  ```json Response theme={null}
  [
    {
      "id": "conv_123abc",
      "agentId": 42,
      "upstreamConversationId": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:45:00.000Z",
      "agentName": "Data Analysis Assistant",
      "agentModel": "gpt-4",
      "agentLogoUrl": "https://example.com/agent-logo.png",
      "userId": "user_2ABC123DEF",
      "userEmail": "john.doe@company.com",
      "userFirstName": "John",
      "userLastName": "Doe",
      "userPublicMetadata": {
        "department": "engineering",
        "role": "senior-developer"
      },
      "firstMessageText": "Can you help me analyze this dataset?",
      "userMessageCount": 3,
      "assistantMessageCount": 3,
      "totalMessageCount": 6,
      "duration": 900,
      "totalTokens": 2847,
      "inputTokens": 1923,
      "outputTokens": 924,
      "attachmentCount": 1,
      "toolCalls": [
        {
          "toolName": "execute_python",
          "args": {
            "code": "import pandas as pd\ndf = pd.read_csv('data.csv')\nprint(df.head())"
          },
          "result": "DataFrame with 1000 rows displayed"
        }
      ],
      "lastFinishReason": "stop",
      "totalFeedback": 1,
      "totalHelpful": 1,
      "totalNotHelpful": 0,
      "feedbackData": [
        {
          "rating": "helpful",
          "comment": "Great analysis!",
          "timestamp": "2024-01-15T10:45:00.000Z"
        }
      ],
      "subConversations": []
    }
  ]
  ```
</CodeGroup>

### Error Codes

<ResponseField name="403" type="object">
  Forbidden - User lacks required permissions (e.g., non-admin trying to use `allInOrg=true`)
</ResponseField>

<ResponseField name="500" type="object">
  Internal Server Error - Server encountered an unexpected condition
</ResponseField>

## Notes

* Results are ordered by `updatedAt` in descending order (most recent first)
* Conversations marked as deleted (`deletedAt` is not null) are excluded from results
* Sub-conversations are nested under their parent conversation in the `subConversations` array
* Tool calls include the complete invocation data with arguments and results
* **Metadata filtering is organization-scoped**: Only searches within the current organization's user metadata
* Metadata filtering supports flexible querying across user's publicMetadata JSON field
* All dates are returned in ISO 8601 format
* When `allInOrg=true`, only users with `org:admin` role can access organization-wide data