> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Append tool invocations to a call > Attach tool invocations that fired during a call to an already-existing call, asynchronously after the call was created. Use this when the tool-call data becomes available later than the call itself (e.g. a Roark simulation, or a call submitted via POST /v1/call before its tools were ready). Writes are idempotent: re-sending an invocation already present on the call (same tool name and timing) is skipped, so retries converge instead of double-counting. Optionally pass `metrics` to (re)score metrics over the newly attached tools, which triggers a billed metric collection job and requires the `metric:create` permission. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/call/{callId}/tool-invocations openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Config - name: CLI Auth - name: Call Analysis - name: Health paths: /v1/call/{callId}/tool-invocations: post: tags: - Call summary: Append tool invocations to a call description: >- Attach tool invocations that fired during a call to an already-existing call, asynchronously after the call was created. Use this when the tool-call data becomes available later than the call itself (e.g. a Roark simulation, or a call submitted via POST /v1/call before its tools were ready). Writes are idempotent: re-sending an invocation already present on the call (same tool name and timing) is skipped, so retries converge instead of double-counting. Optionally pass `metrics` to (re)score metrics over the newly attached tools, which triggers a billed metric collection job and requires the `metric:create` permission. operationId: postV1CallByCallIdTool-invocations parameters: - in: path name: callId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/AppendToolInvocationsRequest' responses: '200': description: Tool invocations attached to the call content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AppendToolInvocationsResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '402': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Insufficient credit example: type: payment_required code: insufficient_credits message: >- Not enough credit to start this work. Add credit and try again. description: Payment Required '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.call.appendToolInvocations('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { toolInvocations: [ { name: 'name', parameters: { foo: 'string' }, result: 'string', startOffsetMs: 0 }, ], }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.call.append_tool_invocations( call_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", tool_invocations=[{ "name": "name", "parameters": { "foo": "string", }, "result": "string", "start_offset_ms": 0, }], ) print(response.data) components: schemas: AppendToolInvocationsRequest: type: object properties: toolInvocations: type: array items: type: object properties: name: type: string description: Name of the tool that was invoked description: type: string description: Description of when the tool should be invoked parameters: type: object additionalProperties: anyOf: - type: object properties: description: type: string type: type: string enum: - string - number - boolean value: {} - {} description: Parameters provided to the tool during invocation result: anyOf: - type: string - type: object additionalProperties: {} description: >- Result returned by the tool after execution. Can be a string or a JSON object startOffsetMs: type: integer minimum: 0 maximum: 2147483647 description: >- Offset in milliseconds from the start of the call when the tool was invoked endOffsetMs: type: integer minimum: 0 maximum: 2147483647 description: >- Offset in milliseconds from the start of the call when the tool execution completed. Used to calculate duration of the tool execution agent: type: object properties: roarkId: type: string format: uuid description: The Roark ID of the agent customId: type: string description: The custom ID set on the agent description: >- Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to required: - name - parameters - result - startOffsetMs minItems: 1 maxItems: 500 description: >- Tool invocations that fired during the call, to attach to it. Max 500 per request. Re-sending an invocation already present on the call (same tool name and timing) is skipped, so retries are safe. metrics: type: array items: type: object properties: id: type: string format: uuid required: - id minItems: 1 maxItems: 20 description: >- Optional. Metric definitions to (re)score on this call after the tool invocations are attached, e.g. the Tool Invocation Analysis metrics. Triggers a metric collection job (billed, credit-gated) and requires the 'metric:create' permission. Omit to attach tools without scoring. Max 20. required: - toolInvocations description: >- Attach tool invocations to an existing call, optionally (re)scoring metrics over them. AppendToolInvocationsResponse: type: object properties: callId: type: string format: uuid description: The call the tool invocations were attached to added: type: integer description: Number of tool invocations newly written skipped: type: integer description: >- Number of tool invocations skipped because an identical one (same tool and timing) already existed on the call metricCollectionJob: oneOf: - $ref: '#/components/schemas/MetricCollectionJobResponse' - type: 'null' description: >- The metric collection job triggered to (re)score the requested metrics, or null when no metrics were requested (or when scoring failed, see metricCollectionError). Track its id to fetch results from GET /v1/metric/collection-jobs/:jobId. metricCollectionError: type: - string - 'null' description: >- Present (non-null) only when `metrics` were requested but the collection job could not be started (e.g. insufficient credits, or an unknown metric id). The tool invocations were still attached — retry scoring via POST /v1/metric/collection-jobs, or re-send this request (attaching is idempotent). Null on success or when no metrics were requested. required: - callId - added - skipped - metricCollectionJob - metricCollectionError description: Result of appending tool invocations to a call. ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message MetricCollectionJobResponse: type: object properties: id: type: string format: uuid description: Unique identifier of the metric collection job status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELED description: Current status of the job triggeredBy: type: string enum: - USER_MANUAL - USER_API - METRIC_POLICY - SIMULATION description: What triggered this job totalItems: type: integer description: Total number of call-metric pairs to process completedItems: type: integer description: Number of successfully completed items failedItems: type: integer description: Number of failed items startedAt: type: - string - 'null' description: When the job started processing completedAt: type: - string - 'null' description: When the job completed errorMessage: type: - string - 'null' description: Error message if the job failed policyIds: type: array items: type: string format: uuid description: IDs of the metric policies that triggered this job createdAt: type: string description: When the job was created updatedAt: type: string description: When the job was last updated required: - id - status - triggeredBy - totalItems - completedItems - failedItems - startedAt - completedAt - errorMessage - policyIds - createdAt - updatedAt description: A metric collection job that processes metrics for calls or chats securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````