Agent Executions

Agent Executions provide a complete audit trail of every time your Portfolio Agent runs. View detailed execution history, analyze patterns, and track your agent's performance over time with paginated access to all past executions.

What Are Agent Executions?

An execution represents a single run of one of your agent's triggers. Each execution record includes:

• Timestamp: When the trigger executed
• Trigger: Which scheduled task initiated this execution
• Status: Success, error, or currently running
• Result: Analysis, recommendations, or insights generated
• Duration: How long the execution took to complete
• Cost: API usage cost for this execution

Execution History Example

Accessing Execution History

Via Portfolio Agent Page

The easiest way to view your execution history is through your portfolio's agent page:

1. Navigate to My Portfolios
2. Select the portfolio with an active agent
3. Click the "Agent" tab
4. Scroll to the "Execution History" section
5. Click "View All Executions" to see paginated history

Via API

You can also access execution history programmatically via the API. See the API Documentation under the Portfolio Agents tag for details on the GET /api/v1/portfolios/:id/agent/executions endpoint.

Pagination

Agent execution history is paginated to efficiently load large volumes of historical data. The default page size is 20 executions, and you can navigate through pages to view older executions.

Pagination Controls

API Pagination

When accessing executions via the API, use the limit and offset query parameters:

Execution Status

Each execution has one of three possible statuses:

Success

The agent successfully analyzed your portfolio and generated recommendations. The result field contains the analysis summary and any suggested actions.

Error

The execution encountered an error and could not complete. Common causes include:

• Network issues connecting to external data sources
• Invalid or unreachable API endpoints
• Malformed prompts or strategy definitions
• Temporary service outages

Running

The execution is currently in progress. This typically lasts a few seconds but may take longer for complex portfolio analysis. The duration field will be populated once the execution completes.

Understanding Execution Results

Result Summary

For successful executions, the result summary contains the agent's analysis and recommendations based on your strategy and the specific trigger prompt. This may include:

• Current portfolio allocations vs. target weights
• Rebalancing suggestions with specific buy/sell amounts
• Performance analysis and profit/loss calculations
• Market condition assessments
• Alerts about positions outside acceptable ranges

Cost Tracking

Each execution displays the API usage cost. This helps you monitor resource consumption, especially if you have frequent triggers or complex analysis prompts.

Execution Duration

Duration shows how long it took the agent to complete the execution, measured in milliseconds. Typical executions complete in 2-5 seconds. Longer durations may indicate:

• Complex portfolio with many holdings to analyze
• Detailed prompts requiring extensive analysis
• Network latency or temporary API slowdowns

Filtering Executions

While the UI currently shows all executions in chronological order, you can use the API to filter executions by specific criteria:

• By Trigger: View executions from a specific trigger only
• By Status: Filter to show only successful or failed executions
• By Date Range: Limit results to a specific time period

Troubleshooting

No Executions Showing

If your execution history is empty, check the following:

• Agent is active (toggle on the agent card)
• At least one trigger is enabled
• Trigger schedule has passed (wait for the next scheduled execution)
• Agent was recently created (no executions yet)

Executions Failing Consistently

If multiple executions show error status:

1. Review error messages for patterns or common causes
2. Verify your agent strategy and trigger prompts are correctly formatted
3. Check if portfolio data is accessible (try manually viewing your portfolio)
4. Test with a simpler prompt to isolate whether the issue is with prompt complexity
5. Contact support if errors persist with detailed execution IDs and error messages

Pagination Not Loading

If you encounter issues loading additional pages:

• Refresh the page to reload execution data
• Check your network connection
• Try viewing executions via the API to verify data availability

Best Practices

Regular Review

Periodically review your agent's execution history to:

• Ensure the agent is providing valuable insights
• Identify patterns in recommendations
• Adjust strategy or prompts based on results
• Verify triggers are executing on schedule

Acting on Recommendations

Remember that agent executions provide analysis only. Review recommendations carefully before taking action:

• Verify data accuracy (prices, allocations)
• Consider current market conditions
• Evaluate risk and potential impact
• Execute trades manually through your exchange or wallet

Cost Management

Monitor execution costs and adjust trigger frequency if needed:

• Daily triggers for active monitoring
• Weekly triggers for long-term strategies
• Disable triggers temporarily when not needed
• Use simpler prompts to reduce analysis complexity and cost

API Reference

For programmatic access to agent executions, use the following endpoint:

Full API documentation, including request/response schemas and authentication, is available in the API Documentation under the Portfolio Agents tag.

Related Documentation

• Portfolio Agents - Learn how to create and configure agents
• Portfolios - Understand portfolio structure and management
• API Documentation - Access agent executions programmatically

Developers can integrate with MyHold App using our REST API. See the API Documentation for details.