API Exécutions

Les exécutions représentent les instances lorsque les agents s’exécutent. Chaque exécution capture l’historique complet des messages, l’utilisation des outils, les résultats et les métriques de performance. Utilisez l’API Exécutions pour surveiller l’activité des agents, suivre l’achèvement des tâches et analyser les modèles d’exécution.

URL de base : https://us.teamday.ai/api/v1/executions

Authentification : Jeton d’accès personnel requis

---

Aperçu des endpoints

Méthode	Endpoint	Description	Statut
GET	/executions	Lister les exécutions	🟡 Non testé
GET	/executions/[id]	Obtenir les détails d’une exécution	🟡 Non testé
GET	/executions/[id]/tree	Obtenir l’arbre d’exécution (sous-agents)	🟡 Non testé
POST	/executions/[id]/cancel	Annuler une exécution en cours	🟡 Non testé

Statut d’implémentation : Complet mais non testé en production

---

Objet Exécution

Propriétés

{
  id: string              // ID de l'exécution (format: exec_xxx)
  agentId: string         // Agent qui a exécuté
  organizationId: string  // Organisation propriétaire
  userId: string          // Utilisateur qui a déclenché l'exécution
  status: string          // "pending" | "running" | "completed" | "failed" | "cancelled"
  startedAt: string       // Horodatage ISO 8601
  completedAt?: string    // Horodatage ISO 8601 (si terminé)
  messages: Message[]     // Historique de la conversation
  toolCalls: ToolCall[]   // Outils utilisés pendant l'exécution
  error?: string          // Message d'erreur (si échec)
  metadata: object        // Contexte d'exécution supplémentaire
}

Exemple d’objet

{
  "id": "exec_xyz789",
  "agentId": "agent_abc123",
  "organizationId": "org_456",
  "userId": "user_789",
  "status": "completed",
  "startedAt": "2025-12-09T10:30:00Z",
  "completedAt": "2025-12-09T10:30:45Z",
  "messages": [
    {
      "role": "user",
      "content": "Analyser ces données de ventes",
      "timestamp": "2025-12-09T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Basé sur l'analyse des données de ventes...",
      "timestamp": "2025-12-09T10:30:45Z"
    }
  ],
  "toolCalls": [
    {
      "tool": "read_file",
      "arguments": { "path": "sales_data.csv" },
      "result": "Success",
      "timestamp": "2025-12-09T10:30:20Z"
    }
  ],
  "metadata": {
    "model": "claude-sonnet-4-6",
    "tokensUsed": 1234,
    "duration": 45000
  }
}

---

Lister les exécutions

Récupérer l’historique d’exécution de votre organisation, optionnellement filtré par agent.

Requête

GET /api/v1/executions

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de requête :

• agentId (string, optionnel) - Filtrer par agent spécifique
• limit (number, optionnel) - Nombre maximum de résultats (par défaut : 50, max : 100)

Réponse

Succès (200 OK) :

[
  {
    "id": "exec_xyz789",
    "agentId": "agent_abc123",
    "organizationId": "org_456",
    "userId": "user_789",
    "status": "completed",
    "startedAt": "2025-12-09T10:30:00Z",
    "completedAt": "2025-12-09T10:30:45Z",
    "metadata": {
      "model": "claude-sonnet-4-6",
      "duration": 45000
    }
  },
  {
    "id": "exec_abc456",
    "agentId": "agent_abc123",
    "organizationId": "org_456",
    "userId": "user_789",
    "status": "running",
    "startedAt": "2025-12-09T11:00:00Z",
    "metadata": {
      "model": "claude-sonnet-4-6"
    }
  }
]

Résultat vide :

[]

Erreur (401 Unauthorized) :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Exemples

Lister toutes les exécutions :

curl https://us.teamday.ai/api/v1/executions \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filtrer par agent :

curl "https://us.teamday.ai/api/v1/executions?agentId=agent_abc123" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Limiter les résultats :

curl "https://us.teamday.ai/api/v1/executions?limit=10" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Combiner les filtres :

curl "https://us.teamday.ai/api/v1/executions?agentId=agent_abc123&limit=25" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

---

Obtenir les détails d’une exécution

Récupérer les détails complets d’une exécution spécifique, incluant l’historique complet des messages et les appels d’outils.

Requête

GET /api/v1/executions/[id]

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de chemin :

• id (string) - ID de l’exécution (format : exec_xxx)

Réponse

Succès (200 OK) :

{
  "id": "exec_xyz789",
  "agentId": "agent_abc123",
  "organizationId": "org_456",
  "userId": "user_789",
  "status": "completed",
  "startedAt": "2025-12-09T10:30:00Z",
  "completedAt": "2025-12-09T10:30:45Z",
  "messages": [
    {
      "role": "user",
      "content": "Analyser ces données de ventes et fournir des insights",
      "timestamp": "2025-12-09T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Je vais analyser les données de ventes pour vous. Laissez-moi d'abord lire le fichier.",
      "timestamp": "2025-12-09T10:30:05Z"
    },
    {
      "role": "tool",
      "content": "Fichier lu avec succès : 1234 lignes de données de ventes",
      "timestamp": "2025-12-09T10:30:20Z"
    },
    {
      "role": "assistant",
      "content": "Basé sur l'analyse des données de ventes :\n\n1. Revenus en hausse de 23% en glissement annuel\n2. Région la plus performante : Côte Ouest (35% du total)\n3. T4 montre la plus forte croissance (+42%)\n\nRecommandations :\n- Concentrer les efforts marketing sur la Côte Ouest\n- Répliquer les stratégies du T4 dans les autres trimestres\n- Enquêter sur les régions sous-performantes",
      "timestamp": "2025-12-09T10:30:45Z"
    }
  ],
  "toolCalls": [
    {
      "tool": "read_file",
      "arguments": {
        "path": "sales_data.csv"
      },
      "result": "Success",
      "timestamp": "2025-12-09T10:30:20Z"
    }
  ],
  "metadata": {
    "model": "claude-sonnet-4-6",
    "tokensUsed": 2847,
    "duration": 45000,
    "toolsUsed": ["read_file"]
  }
}

Erreur (404 Not Found) :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Erreur (401 Unauthorized) :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Exemple

curl https://us.teamday.ai/api/v1/executions/exec_xyz789 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

---

Obtenir l’arbre d’exécution

Récupérer l’arbre d’exécution montrant les relations parent-enfant lorsque les agents délèguent du travail à des sous-agents.

Requête

GET /api/v1/executions/[id]/tree

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de chemin :

• id (string) - ID de l’exécution (format : exec_xxx)

Réponse

Succès (200 OK) :

{
  "root": {
    "id": "exec_parent123",
    "agentId": "agent_orchestrator",
    "status": "completed",
    "startedAt": "2025-12-09T10:00:00Z",
    "completedAt": "2025-12-09T10:05:00Z"
  },
  "children": [
    {
      "id": "exec_child456",
      "agentId": "agent_researcher",
      "parentExecutionId": "exec_parent123",
      "status": "completed",
      "startedAt": "2025-12-09T10:00:30Z",
      "completedAt": "2025-12-09T10:02:00Z",
      "children": []
    },
    {
      "id": "exec_child789",
      "agentId": "agent_writer",
      "parentExecutionId": "exec_parent123",
      "status": "completed",
      "startedAt": "2025-12-09T10:02:30Z",
      "completedAt": "2025-12-09T10:05:00Z",
      "children": []
    }
  ],
  "metadata": {
    "totalExecutions": 3,
    "maxDepth": 2,
    "totalDuration": 300000
  }
}

Exécution unique (pas de sous-agents) :

{
  "root": {
    "id": "exec_xyz789",
    "agentId": "agent_abc123",
    "status": "completed",
    "startedAt": "2025-12-09T10:30:00Z",
    "completedAt": "2025-12-09T10:30:45Z"
  },
  "children": [],
  "metadata": {
    "totalExecutions": 1,
    "maxDepth": 1,
    "totalDuration": 45000
  }
}

Erreur (404 Not Found) :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Exemple

curl https://us.teamday.ai/api/v1/executions/exec_parent123/tree \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Cas d’utilisation

Surveillance de la délégation :

• Suivre quand les agents délèguent à des sous-agents
• Mesurer l’efficacité de la collaboration entre agents
• Déboguer les workflows multi-agents complexes

Analyse de performance :

• Identifier les goulots d’étranglement dans les tâches déléguées
• Comparer la délégation série vs. parallèle
• Optimiser l’orchestration des agents

---

Annuler une exécution

Arrêter une exécution en cours. Seules les exécutions avec le statut pending ou running peuvent être annulées.

Requête

POST /api/v1/executions/[id]/cancel

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de chemin :

• id (string) - ID de l’exécution (format : exec_xxx)

Corps : Aucun

Réponse

Succès (200 OK) :

{
  "success": true,
  "message": "Execution cancelled successfully",
  "execution": {
    "id": "exec_xyz789",
    "status": "cancelled",
    "cancelledAt": "2025-12-09T10:35:00Z"
  }
}

Erreur (400 Bad Request - Déjà terminée) :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Cannot cancel execution: already completed"
}

Erreur (404 Not Found) :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Exemple

curl -X POST https://us.teamday.ai/api/v1/executions/exec_xyz789/cancel \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Notes

Comportement d’annulation :

• L’exécution est immédiatement marquée comme cancelled
• L’agent arrête le traitement (meilleur effort)
• Les résultats partiels peuvent être sauvegardés
• Impossible de reprendre une exécution annulée
• Les sous-agents (le cas échéant) sont également annulés

Quand annuler :

• Exécution longue prenant trop de temps
• Agent bloqué dans une boucle infinie
• L’utilisateur a changé les exigences
• Buts de test/débogage

---

Statut d’exécution

Les exécutions progressent à travers les états suivants :

Pending

Statut : "pending"

Description : Exécution créée mais pas encore démarrée. En attente de ressources ou en file d’attente.

Durée : Habituellement < 1 seconde

États suivants : running, cancelled

Running

Statut : "running"

Description : Agent en cours de traitement. Peut impliquer plusieurs appels d’outils et requêtes API.

Durée : Variable (secondes à minutes)

États suivants : completed, failed, cancelled

Completed

Statut : "completed"

Description : Exécution terminée avec succès. Résultats disponibles.

État terminal : Oui (pas de transitions ultérieures)

Failed

Statut : "failed"

Description : L’exécution a rencontré une erreur et s’est arrêtée. Vérifier le champ error pour les détails.

État terminal : Oui (pas de transitions ultérieures)

Causes courantes :

• Erreurs API (limites de débit, service indisponible)
• Appels d’outils invalides
• Erreurs de permissions
• Timeout

Cancelled

Statut : "cancelled"

Description : Exécution arrêtée manuellement via l’endpoint d’annulation.

État terminal : Oui (pas de transitions ultérieures)

---

Filtrage et pagination

Par agent

Filtrer les exécutions pour un agent spécifique :

curl "https://us.teamday.ai/api/v1/executions?agentId=agent_abc123" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Par statut (Futur)

Bientôt disponible : Filtrer par statut d’exécution

# Fonctionnalité future
curl "https://us.teamday.ai/api/v1/executions?status=running" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Pagination

Contrôler le nombre de résultats :

# Obtenir les 10 premières exécutions
curl "https://us.teamday.ai/api/v1/executions?limit=10" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Obtenir jusqu'à 100 exécutions
curl "https://us.teamday.ai/api/v1/executions?limit=100" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Valeurs par défaut :

• Limite par défaut : 50
• Limite maximale : 100
• Résultats triés par startedAt (plus récent en premier)

Pagination par offset (Futur) :

# Fonctionnalité future
curl "https://us.teamday.ai/api/v1/executions?limit=50&offset=50" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

---

Métriques de performance

Les métadonnées d’exécution incluent les données de performance :

Durée

Champ : metadata.duration (millisecondes)

Calcul : completedAt - startedAt

Cas d’utilisation :

• Suivre le temps de réponse moyen de l’agent
• Identifier les exécutions lentes
• Optimiser les prompts des agents

Utilisation de tokens

Champ : metadata.tokensUsed (nombre)

Description : Total des tokens consommés (entrée + sortie)

Cas d’utilisation :

• Estimer les coûts de l’API
• Optimiser la longueur des prompts
• Surveiller l’efficacité des tokens

Modèle

Champ : metadata.model (string)

Exemple : "claude-sonnet-4-6"

Cas d’utilisation :

• Suivre quels modèles sont utilisés
• Comparer la performance entre modèles
• Auditer la sélection de modèles

Outils utilisés

Champ : metadata.toolsUsed (tableau de chaînes)

Exemple : ["read_file", "write_file", "bash"]

Cas d’utilisation :

• Comprendre le comportement des agents
• Suivre les modèles d’utilisation des outils
• Déboguer les problèmes liés aux outils

---

Modèles courants

Surveiller les exécutions en cours

Interroger les exécutions en cours pour surveiller l’activité des agents :

async function getRunningExecutions() {
  const response = await fetch('https://us.teamday.ai/api/v1/executions', {
    headers: {
      'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
    }
  })

  const executions = await response.json()

  return executions.filter(exec => exec.status === 'running')
}

// Vérifier toutes les 5 secondes
setInterval(async () => {
  const running = await getRunningExecutions()
  console.log(`${running.length} exécutions en cours`)
}, 5000)

Suivre la performance des agents

Calculer le temps d’exécution moyen par agent :

async function getAgentPerformance(agentId) {
  const response = await fetch(
    `https://us.teamday.ai/api/v1/executions?agentId=${agentId}&limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
      }
    }
  )

  const executions = await response.json()

  const completed = executions.filter(e => e.status === 'completed')

  const avgDuration = completed.reduce((sum, e) => {
    return sum + e.metadata.duration
  }, 0) / completed.length

  const avgTokens = completed.reduce((sum, e) => {
    return sum + (e.metadata.tokensUsed || 0)
  }, 0) / completed.length

  return {
    totalExecutions: executions.length,
    completedExecutions: completed.length,
    avgDuration: Math.round(avgDuration),
    avgTokens: Math.round(avgTokens)
  }
}

Annuler les exécutions longues

Annuler automatiquement les exécutions dépassant un timeout :

async function cancelLongRunning(timeoutMs = 300000) { // 5 minutes
  const response = await fetch('https://us.teamday.ai/api/v1/executions', {
    headers: {
      'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
    }
  })

  const executions = await response.json()
  const now = Date.now()

  for (const exec of executions) {
    if (exec.status !== 'running') continue

    const startedAt = new Date(exec.startedAt).getTime()
    const elapsed = now - startedAt

    if (elapsed > timeoutMs) {
      console.log(`Annulation de l'exécution ${exec.id} (en cours ${elapsed}ms)`)

      await fetch(`https://us.teamday.ai/api/v1/executions/${exec.id}/cancel`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
        }
      })
    }
  }
}

---

Gestion des erreurs

Erreurs courantes

400 Bad Request :

• Tentative d’annulation d’une exécution terminée/échouée
• Paramètres de requête invalides

401 Unauthorized :

• En-tête Authorization manquant
• Jeton invalide ou expiré

404 Not Found :

• L’ID de l’exécution n’existe pas
• L’exécution appartient à une autre organisation

500 Internal Server Error :

• Problèmes de connectivité de base de données
• Service temporairement indisponible

Stratégie de nouvelle tentative

Pour les échecs transitoires, implémenter un backoff exponentiel :

async function getExecutionWithRetry(executionId, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        `https://us.teamday.ai/api/v1/executions/${executionId}`,
        {
          headers: {
            'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
          }
        }
      )

      if (!response.ok) {
        const error = await response.json()

        // Ne pas réessayer les erreurs client
        if (response.status >= 400 && response.status < 500) {
          throw new Error(error.message)
        }

        // Réessayer les erreurs serveur
        if (i === maxRetries - 1) throw new Error(error.message)

        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, i) * 1000)
        )
        continue
      }

      return await response.json()

    } catch (err) {
      if (i === maxRetries - 1) throw err
    }
  }
}

---

Bonnes pratiques

Surveillance

Fréquence d’interrogation :

• Exécutions en cours : 2-5 secondes
• Exécutions terminées : Pas d’interrogation nécessaire (utiliser les webhooks quand disponibles)

Que surveiller :

• Exécutions bloquées en running > 5 minutes
• Taux d’échec élevé (> 10%)
• Pics inhabituels d’utilisation de tokens

Stockage

Rétention des exécutions :

• Conserver les exécutions récentes (30 derniers jours) pour le débogage
• Archiver les exécutions plus anciennes pour la conformité
• Supprimer les données sensibles selon la politique de rétention

Note : TeamDay conserve actuellement toutes les exécutions indéfiniment. Suppression en libre-service à venir.

Performance

Optimiser les prompts des agents :

• Surveiller metadata.tokensUsed pour réduire les coûts
• Suivre metadata.duration pour améliorer le temps de réponse
• Examiner toolCalls pour minimiser l’utilisation inutile d’outils

Exécution parallèle :

• Exécuter plusieurs agents simultanément (pas de limites API actuellement)
• Utiliser les arbres d’exécution pour les modèles de délégation
• Surveiller le total des exécutions actives

---

Ressources associées

• API Agents - Créer et gérer les agents
• API Tâches - Gérer les tâches des agents
• Authentification - Configuration du jeton PAT
• Référence des erreurs - Documentation complète des erreurs

---

Besoin d’aide ?

Problèmes avec les exécutions ?

• Consultez la référence des erreurs pour le dépannage
• Surveillez le statut d’exécution et les messages d’erreur
• Utilisez les arbres d’exécution pour déboguer la délégation

Questions ?

• 📧 Email : support at teamday.ai
• 💬 Discord : Rejoindre la communauté
• 🐛 Signaler des bugs : Problèmes GitHub

---

Dernière mise à jour : 9 décembre 2025