> ## Documentation Index > Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get project_automation > Get a project_automation object by its id ## OpenAPI ````yaml /openapi.yaml get /v1/project_automation/{project_automation_id} openapi: 3.1.1 info: version: 1.0.0 title: Braintrust API description: >- API specification for the backend data server. The API is hosted globally at https://api.braintrust.dev or in your own environment. You can access the OpenAPI spec for this API at https://github.com/braintrustdata/braintrust-openapi. license: name: Apache 2.0 servers: - url: https://api.braintrust.dev security: - bearerAuth: [] - {} paths: /v1/project_automation/{project_automation_id}: get: tags: - ProjectAutomations summary: Get project_automation description: Get a project_automation object by its id operationId: getProjectAutomationId parameters: - $ref: '#/components/parameters/ProjectAutomationIdParam' responses: '200': description: Returns the project_automation object content: application/json: schema: $ref: '#/components/schemas/ProjectAutomation' '400': description: >- The request was unacceptable, often due to missing a required parameter content: text/plain: schema: type: string application/json: schema: nullable: true '401': description: No valid API key provided content: text/plain: schema: type: string application/json: schema: nullable: true '403': description: The API key doesn’t have permissions to perform the request content: text/plain: schema: type: string application/json: schema: nullable: true '429': description: >- Too many requests hit the API too quickly. We recommend an exponential backoff of your requests headers: Retry-After: schema: type: string content: text/plain: schema: type: string application/json: schema: nullable: true '500': description: Something went wrong on Braintrust's end. (These are rare.) content: text/plain: schema: type: string application/json: schema: nullable: true security: - bearerAuth: [] - {} components: parameters: ProjectAutomationIdParam: schema: $ref: '#/components/schemas/ProjectAutomationIdParam' required: true description: ProjectAutomation id name: project_automation_id in: path schemas: ProjectAutomation: type: object properties: id: type: string format: uuid description: Unique identifier for the project automation project_id: type: string format: uuid description: >- Unique identifier for the project that the project automation belongs under user_id: type: string nullable: true format: uuid description: Identifies the user who created the project automation created: type: string nullable: true format: date-time description: Date of project automation creation name: type: string description: Name of the project automation description: type: string nullable: true description: Textual description of the project automation config: oneOf: - type: object properties: event_type: type: string enum: - logs description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' btql_filter: type: string description: BTQL filter to identify rows for the automation rule interval_seconds: type: number minimum: 1 maximum: 2592000 description: >- Perform the triggered action at most once in this interval of seconds action: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Instructions for Loop to format content sent to this destination required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Publish a Slack mrkdwn digest. Pattern selection requirement: include every selected Pattern whose final status is active at the end of this automation run, plus every selected Pattern that changed from active to inactive during this run (a newly inactive outcome). Exclude Patterns that were already inactive before this run and remained inactive. Do not mention excluded Patterns anywhere in the digest, including Highlights. If no selected Patterns meet these criteria, say "No current pattern outcomes." This requirement overrides conflicting formatting guidance. Include a complete "*Pattern outcomes*" section with one row for every included Pattern. Use this row format exactly: • — `outcome` If a Pattern has no URL, use the plain title instead. Do not use GitHub Markdown tables or code-block tables, because links must remain clickable. Do not omit any active selected Pattern. After the outcome list, include a "*Highlights*" section with one very short paragraph, 2-3 sentences maximum. Summarize what changed or what broadly stands out among the included active Patterns. Do not introduce new claims beyond the run report. required: - type - workspace_id - channel description: The action to take when the automation rule is triggered required: - event_type - btql_filter - interval_seconds - action - type: object properties: event_type: type: string enum: - btql_export description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' export_definition: oneOf: - type: object properties: type: type: string enum: - log_traces required: - type - type: object properties: type: type: string enum: - log_spans required: - type - type: object properties: type: type: string enum: - btql_query btql_query: type: string description: The BTQL query to export required: - type - btql_query description: The definition of what to export scope: anyOf: - $ref: '#/components/schemas/SpanScope' - $ref: '#/components/schemas/TraceScope' - $ref: '#/components/schemas/GroupScope' - type: 'null' description: >- Execution scope for export automation. Defaults to span-level execution. export_path: type: string description: >- The path to export the results to. It should include the storage protocol and prefix, e.g. s3://bucket-name/path/to/export format: type: string enum: - jsonl - parquet description: The format to export the results in interval_seconds: type: number minimum: 1 maximum: 2592000 description: >- Perform the triggered action at most once in this interval of seconds credentials: oneOf: - type: object properties: type: type: string enum: - aws_iam role_arn: type: string description: The ARN of the IAM role to use external_id: type: string description: >- The automation-specific external id component (auto-generated by default) required: - type - role_arn - external_id - type: object properties: type: type: string enum: - gcp_service_account service_account_email: type: string description: The GCP service account email to impersonate required: - type - service_account_email batch_size: type: number nullable: true description: The number of rows to export in each batch required: - event_type - export_definition - export_path - format - interval_seconds - credentials - type: object properties: event_type: type: string enum: - async_query description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' created_by_user_id: type: string format: uuid description: The user who submitted the async query object_type: type: string enum: - project_logs - experiment - dataset - playground_logs description: The source object type for the async query object_id: type: string description: The source object ID for the async query query: type: string description: The SQL query to execute asynchronously format: type: string enum: - jsonl description: The materialized result format batch_size: type: integer nullable: true minimum: 0 exclusiveMinimum: true maximum: 100000 description: >- The maximum number of result rows to write per async query batch required: - event_type - created_by_user_id - object_type - object_id - query - format - type: object properties: event_type: type: string enum: - retention description: The type of automation. object_type: $ref: '#/components/schemas/RetentionObjectType' retention_days: type: integer minimum: 0 description: The number of days to retain the object required: - event_type - object_type - retention_days - type: object properties: event_type: type: string enum: - environment_update description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' environment_filter: type: array items: type: string description: Optional list of environment slugs to filter by action: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Instructions for Loop to format content sent to this destination required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Publish a Slack mrkdwn digest. Pattern selection requirement: include every selected Pattern whose final status is active at the end of this automation run, plus every selected Pattern that changed from active to inactive during this run (a newly inactive outcome). Exclude Patterns that were already inactive before this run and remained inactive. Do not mention excluded Patterns anywhere in the digest, including Highlights. If no selected Patterns meet these criteria, say "No current pattern outcomes." This requirement overrides conflicting formatting guidance. Include a complete "*Pattern outcomes*" section with one row for every included Pattern. Use this row format exactly: • — `outcome` If a Pattern has no URL, use the plain title instead. Do not use GitHub Markdown tables or code-block tables, because links must remain clickable. Do not omit any active selected Pattern. After the outcome list, include a "*Highlights*" section with one very short paragraph, 2-3 sentences maximum. Summarize what changed or what broadly stands out among the included active Patterns. Do not introduce new claims beyond the run report. required: - type - workspace_id - channel description: The action to take when the automation rule is triggered required: - event_type - action - $ref: '#/components/schemas/WindowedAutomationConfig' - $ref: '#/components/schemas/TopicAutomationConfig' - $ref: '#/components/schemas/TopicDigestAutomationConfig' description: The configuration for the automation rule runtime_block: type: object properties: reason: type: string model: type: string required: - reason - model required: - id - project_id - name - config ProjectAutomationIdParam: type: string format: uuid description: ProjectAutomation id AutomationStatus: type: string enum: - active - paused description: Whether the automation is active or paused. SpanScope: type: object properties: type: type: string enum: - span required: - type description: Process individual spans TraceScope: type: object properties: type: type: string enum: - trace idle_seconds: type: number description: >- Consider trace complete after this many seconds of inactivity (default: 30) required: - type description: Process entire traces (all spans sharing the same root_span_id) GroupScope: type: object properties: type: type: string enum: - group group_by: type: string description: Field path to group by, e.g. metadata.session_id interval_seconds: type: number minimum: 1 description: Maximum time range to include when constructing a group max_traces: type: integer minimum: 1 maximum: 64 description: >- Maximum number of traces to include when constructing a group (default/max: 64) placement: type: string enum: - first - each description: Which trace or traces to write grouped scorer results to idle_seconds: type: number description: 'Optional: trigger after this many seconds of inactivity' required: - type - group_by - placement description: Process spans/traces grouped by a field (e.g., session_id) RetentionObjectType: type: string enum: - project_logs - experiment - dataset description: The object type that the retention policy applies to WindowedAutomationConfig: type: object properties: event_type: type: string enum: - windowed description: The type of automation. product_origin: type: string nullable: true enum: - patterns - null description: The product surface that created and manages the automation status: $ref: '#/components/schemas/AutomationStatus' threshold: type: object properties: calculation: oneOf: - type: object properties: type: type: string enum: - btql btql_query: type: string minLength: 1 description: >- A project-scoped BTQL or SQL query without runtime-owned evaluation time bounds output: type: object properties: type: type: string enum: - scalar value_column: type: string minLength: 1 description: The numeric result column produced by the query required: - type - value_column required: - type - btql_query - output description: The calculation evaluated for each window policy: type: object properties: condition: type: object properties: type: type: string enum: - threshold operator: type: string enum: - lt - lte - gt - gte - eq - neq threshold: type: number required: - type - operator - threshold pending_seconds: type: integer minimum: 0 maximum: 2592000 description: How long the condition must remain breached before firing no_data_behavior: type: string enum: - keep_last - resolve - alert description: >- How the lifecycle changes when the calculation returns no data renotify_interval_seconds: type: integer nullable: true minimum: 1 maximum: 2592000 description: Optional reminder interval while the automation is firing notify_on_recovery: type: boolean default: true description: Whether to deliver actions when a firing automation recovers required: - condition - pending_seconds - no_data_behavior description: The lifecycle policy applied to each calculation result required: - calculation - policy description: >- Optional calculation and lifecycle policy that gate scheduled delivery window: type: object properties: window_seconds: type: integer minimum: 1 maximum: 2592000 description: How much recent data each scheduled run covers schedule: oneOf: - type: object properties: type: type: string enum: - interval evaluation_interval_seconds: type: integer minimum: 1 maximum: 2592000 description: How often the automation runs required: - type - evaluation_interval_seconds - type: object properties: type: type: string enum: - cron cron_expression: type: string minLength: 1 description: >- A standard five-field cron expression (minute hour day-of-month month day-of-week) controlling when the automation runs timezone: type: string nullable: true minLength: 1 description: >- IANA timezone used to interpret the cron expression (defaults to UTC) required: - type - cron_expression description: >- How often the windowed automation runs: at a fixed interval or on a cron schedule evaluation_delay_seconds: type: integer minimum: 0 maximum: 2592000 description: How far behind the present each evaluation window ends required: - window_seconds - schedule - evaluation_delay_seconds loop: type: object properties: prompt: type: string minLength: 1 maxLength: 10000 description: Instructions for the Loop agent include_trigger_input: type: boolean default: false description: Whether to include the automation trigger payload as input agent_slug: type: string minLength: 1 description: The Loop agent to run auto_approve_tools: type: array items: type: string minLength: 1 default: [] description: Write tools that may run without interactive approval harness: type: string enum: - native - codex - claude-code model: type: string minLength: 1 endpoint_name: type: string minLength: 1 reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh - max required: - prompt - agent_slug description: Optional Loop agent to run for each triggered window actions: type: array items: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Instructions for Loop to format content sent to this destination required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Publish a Slack mrkdwn digest. Pattern selection requirement: include every selected Pattern whose final status is active at the end of this automation run, plus every selected Pattern that changed from active to inactive during this run (a newly inactive outcome). Exclude Patterns that were already inactive before this run and remained inactive. Do not mention excluded Patterns anywhere in the digest, including Highlights. If no selected Patterns meet these criteria, say "No current pattern outcomes." This requirement overrides conflicting formatting guidance. Include a complete "*Pattern outcomes*" section with one row for every included Pattern. Use this row format exactly: • — `outcome` If a Pattern has no URL, use the plain title instead. Do not use GitHub Markdown tables or code-block tables, because links must remain clickable. Do not omit any active selected Pattern. After the outcome list, include a "*Highlights*" section with one very short paragraph, 2-3 sentences maximum. Summarize what changed or what broadly stands out among the included active Patterns. Do not introduce new claims beyond the run report. required: - type - workspace_id - channel description: A delivery action available to an automation maxItems: 20 default: [] description: >- Delivery actions exposed to Loop as tools, or run directly when Loop is not configured required: - event_type - window TopicAutomationConfig: type: object properties: event_type: type: string enum: - topic description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' sampling_rate: type: number minimum: 0 maximum: 1 description: The sampling rate for topic automation facet_model: $ref: '#/components/schemas/TopicAutomationFacetModel' facet_functions: type: array items: allOf: - $ref: '#/components/schemas/SavedFunctionId' - anyOf: - type: object properties: type: type: string enum: - function id: type: string version: type: string description: The version of the function required: - type - id title: function - type: object properties: type: type: string enum: - global name: type: string function_type: $ref: '#/components/schemas/FunctionTypeEnum' required: - type - name title: global description: Facet functions used by the topic automation topic_map_functions: type: array items: $ref: '#/components/schemas/TopicMapFunctionAutomation' description: Topic map functions with optional per-topic-map filters scope: anyOf: - $ref: '#/components/schemas/SpanScope' - $ref: '#/components/schemas/TraceScope' - $ref: '#/components/schemas/GroupScope' - type: 'null' description: Execution scope for topic automation. data_scope: $ref: '#/components/schemas/TopicAutomationDataScope' btql_filter: type: string nullable: true description: Optional BTQL filter applied before topic automation. rerun_seconds: type: number nullable: true minimum: 600 description: How often to recompute topic maps relabel_overlap_seconds: type: number nullable: true minimum: 60 description: >- Deprecated. How much recent history to relabel after a new topic map version becomes active. Data planes v2.15.0 and later ignore this and apply a topic map version after the first only to traces classified once it is active. backfill_time_range: anyOf: - type: string - type: object properties: from: type: string to: type: string required: - from - to - type: 'null' description: Topic window used for classification coverage and initial backfill. required: - event_type - sampling_rate - facet_functions - topic_map_functions TopicDigestAutomationConfig: type: object properties: event_type: type: string enum: - topic_digest description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' window_seconds: type: integer minimum: 3600 maximum: 2592000 default: 86400 description: How much recent history to include in each digest scheduled_time_minutes_utc: type: integer minimum: 0 maximum: 1439 description: Minutes after midnight UTC when the digest should be sent action: type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert formatting_prompt: type: string minLength: 1 maxLength: 10000 description: >- Publish a Slack mrkdwn digest. Pattern selection requirement: include every selected Pattern whose final status is active at the end of this automation run, plus every selected Pattern that changed from active to inactive during this run (a newly inactive outcome). Exclude Patterns that were already inactive before this run and remained inactive. Do not mention excluded Patterns anywhere in the digest, including Highlights. If no selected Patterns meet these criteria, say "No current pattern outcomes." This requirement overrides conflicting formatting guidance. Include a complete "*Pattern outcomes*" section with one row for every included Pattern. Use this row format exactly: • — `outcome` If a Pattern has no URL, use the plain title instead. Do not use GitHub Markdown tables or code-block tables, because links must remain clickable. Do not omit any active selected Pattern. After the outcome list, include a "*Highlights*" section with one very short paragraph, 2-3 sentences maximum. Summarize what changed or what broadly stands out among the included active Patterns. Do not introduce new claims beyond the run report. required: - type - workspace_id - channel description: The Slack action to take when the digest is sent topic_map_function_ids: type: array items: type: string maxItems: 10 description: Optional topic map function IDs to include in the digest required: - event_type - scheduled_time_minutes_utc - action TopicAutomationFacetModel: type: string nullable: true enum: - brain-facet-latest - brain-facet-1 - brain-facet-2 - null description: Optional facet model override for topic automation SavedFunctionId: anyOf: - type: object properties: type: type: string enum: - function id: type: string version: type: string description: The version of the function required: - type - id title: function - type: object properties: type: type: string enum: - global name: type: string function_type: $ref: '#/components/schemas/FunctionTypeEnum' required: - type - name title: global - type: 'null' description: Optional function identifier that produced the classification FunctionTypeEnum: type: string enum: - llm - scorer - task - tool - custom_view - preprocessor - facet - classifier - tag - parameters - sandbox - null default: scorer description: The type of global function. Defaults to 'scorer'. TopicMapFunctionAutomation: type: object properties: function: allOf: - $ref: '#/components/schemas/SavedFunctionId' - anyOf: - type: object properties: type: type: string enum: - function id: type: string version: type: string description: The version of the function required: - type - id title: function - type: object properties: type: type: string enum: - global name: type: string function_type: $ref: '#/components/schemas/FunctionTypeEnum' required: - type - name title: global description: Topic map function btql_filter: type: string nullable: true description: >- Per-topic-map BTQL filter. For trace scope, a topic map runs when max(filter) over the trace is truthy. For span scope, it runs when the current span matches. required: - function TopicAutomationDataScope: anyOf: - type: object properties: type: type: string enum: - project_logs required: - type - type: object properties: type: type: string enum: - project_experiments required: - type - type: object properties: type: type: string enum: - experiment experiment_id: type: string required: - type - experiment_id - type: 'null' description: Optional data scope for topic automation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key or JWT description: >- Most Braintrust endpoints are authenticated by providing your API key as a header `Authorization: Bearer [api_key]` to your HTTP request. You can create an API key in the Braintrust [organization settings page](https://www.braintrustdata.com/app/settings?subroute=api-keys). ````