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

# run custom report draft

> run a draft's frozen code before saving it, on its own inputs or another ticker, session or date range; market and granularity stay locked. no AI credits; uses your run allowance and a run slot. returns the result with every row and stores nothing: the draft is not saved and the run cannot be read again. stopped after three minutes. the response stays open until the work finishes or is stopped at its time limit: allow a read timeout of ten minutes, and do not send the request again while it runs. disconnecting cancels the work. a failure after the first ten seconds arrives as 200 with status failed. requires the key's write permission.



## OpenAPI

````yaml /openapi-public.json post /v1/custom-reports/drafts/{conversation_id}/runs
openapi: 3.1.0
info:
  title: Edgeful API
  description: >-
    Public API reference for Edgeful market analysis. The bearer token is your
    Edgeful API key. Reports support the docs playground. Report responses
    include row-level output in `detailed` only when your plan includes
    row-level detail.
  version: 1.0.0
servers:
  - url: https://api.edgeful.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: reports
  - name: discovery
  - name: live data
  - name: settings
  - name: custom reports
  - name: optimizer
paths:
  /v1/custom-reports/drafts/{conversation_id}/runs:
    post:
      tags:
        - custom reports
      summary: run custom report draft
      description: >-
        run a draft's frozen code before saving it, on its own inputs or another
        ticker, session or date range; market and granularity stay locked. no AI
        credits; uses your run allowance and a run slot. returns the result with
        every row and stores nothing: the draft is not saved and the run cannot
        be read again. stopped after three minutes. the response stays open
        until the work finishes or is stopped at its time limit: allow a read
        timeout of ten minutes, and do not send the request again while it runs.
        disconnecting cancels the work. a failure after the first ten seconds
        arrives as 200 with status failed. requires the key's write permission.
      operationId: run_custom_report_draft
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: the builder conversation's id, from build custom report.
            title: Conversation Id
          description: the builder conversation's id, from build custom report.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomReportDraftRunRequest'
            examples:
              default:
                summary: run the draft on NQ over the last year
                value:
                  message_id: a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60
                  controls:
                    ticker: NQ
                    start_date: '2025-10-01'
                    end_date: '2026-09-30'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportDraftRunResult'
        '403':
          description: >-
            Valid API key, but the account has no API-enabled subscription or
            the key's writes are off.
          content:
            application/json:
              examples:
                missing_entitlement:
                  summary: missing entitlement
                  value:
                    detail:
                      detail: No active subscription with API access found.
                      code: missing_entitlement
                writes_disabled:
                  summary: writes disabled
                  value:
                    detail:
                      detail: >-
                        Allow changes through your API key or the MCP connector
                        in the API dashboard.
                      code: writes_disabled
        '404':
          description: the builder conversation or message is not yours, or does not exist.
        '409':
          description: >-
            the build has not completed, or no completed session data covers the
            requested dates.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            The account's custom report run write budget is exhausted; wait
            `Retry-After` seconds. Refused attempts count too.
          content:
            application/json:
              examples:
                write_budget_exhausted:
                  summary: write budget exhausted
                  value:
                    detail:
                      detail: >-
                        Custom report run write limit reached. Try again
                        shortly.
                      code: write_budget_exhausted
          headers:
            Retry-After:
              description: seconds to wait before sending the write again.
              schema:
                type: integer
        '503':
          description: The write budget could not be checked; retry shortly.
          content:
            application/json:
              examples:
                write_limits_unavailable:
                  summary: write limits unavailable
                  value:
                    detail:
                      detail: >-
                        Custom report run write limits are temporarily
                        unavailable. Try again shortly.
                      code: write_limits_unavailable
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url 'https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs' \
              --header 'Authorization: Bearer <api-key>' \
              --header 'Content-Type: application/json' \
              --data '{"message_id": "a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60", "controls": {"ticker": "NQ", "start_date": "2025-10-01", "end_date": "2026-09-30"}}'
        - lang: python
          label: Python
          source: >-
            import requests


            url =
            "https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs"

            headers = {"Authorization": "Bearer <api-key>"}

            payload = {'message_id': 'a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60',
            'controls': {'ticker': 'NQ', 'start_date': '2025-10-01', 'end_date':
            '2026-09-30'}}


            response = requests.post(url, headers=headers, json=payload)

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const url =
            "https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs";

            const options = {
              method: "POST",
              headers: { Authorization: "Bearer <api-key>", "Content-Type": "application/json" },
              body: JSON.stringify({"message_id": "a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60", "controls": {"ticker": "NQ", "start_date": "2025-10-01", "end_date": "2026-09-30"}}),
            };


            const response = await fetch(url, options);

            const data = await response.json();

            console.log(data);
        - lang: php
          label: PHP
          source: >-
            <?php

            $ch =
            curl_init("https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs");

            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");

            curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer
            <api-key>", "Content-Type: application/json"]);

            curl_setopt($ch, CURLOPT_POSTFIELDS, '{"message_id":
            "a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60", "controls": {"ticker": "NQ",
            "start_date": "2025-10-01", "end_date": "2026-09-30"}}');

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            $response = curl_exec($ch);

            curl_close($ch);

            echo $response;
        - lang: go
          label: Go
          source: |-
            package main

            import (
                "fmt"
                "io"
                "net/http"
                "strings"
            )

            func main() {
                req, _ := http.NewRequest("POST", "https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs", strings.NewReader(`{"message_id": "a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60", "controls": {"ticker": "NQ", "start_date": "2025-10-01", "end_date": "2026-09-30"}}`))
                req.Header.Set("Authorization", "Bearer <api-key>")
                req.Header.Set("Content-Type", "application/json")
                resp, _ := http.DefaultClient.Do(req)
                defer resp.Body.Close()
                body, _ := io.ReadAll(resp.Body)
                fmt.Println(string(body))
            }
        - lang: java
          label: Java
          source: >-
            import java.net.URI;

            import java.net.http.HttpClient;

            import java.net.http.HttpRequest;

            import java.net.http.HttpResponse;


            HttpClient client = HttpClient.newHttpClient();

            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs"))
                .header("Authorization", "Bearer <api-key>")
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString("{\"message_id\": \"a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60\", \"controls\": {\"ticker\": \"NQ\", \"start_date\": \"2025-10-01\", \"end_date\": \"2026-09-30\"}}"))
                .build();
            HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

            System.out.println(response.body());
        - lang: ruby
          label: Ruby
          source: >-
            require "net/http"

            require "uri"


            uri =
            URI("https://api.edgeful.com/v1/custom-reports/drafts/<conversation_id>/runs")

            request = Net::HTTP::Post.new(uri)

            request["Authorization"] = "Bearer <api-key>"

            request["Content-Type"] = "application/json"

            request.body = '{"message_id":
            "a3e1f2d4-6c5b-4e7a-8f90-1b2c3d4e5f60", "controls": {"ticker": "NQ",
            "start_date": "2025-10-01", "end_date": "2026-09-30"}}'


            response = Net::HTTP.start(uri.hostname, uri.port, use_ssl:
            uri.scheme == "https") do |http|
              http.request(request)
            end

            puts response.body
components:
  schemas:
    CustomReportDraftRunRequest:
      properties:
        message_id:
          type: string
          format: uuid
          title: Message Id
          description: the successful builder message whose draft to run.
        controls:
          anyOf:
            - $ref: '#/components/schemas/ReportControls'
            - type: 'null'
          description: the inputs to change; omit to run the draft's own inputs.
      additionalProperties: false
      type: object
      required:
        - message_id
      title: CustomReportDraftRunRequest
    CustomReportDraftRunResult:
      properties:
        summary:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the result's summary values.
        detailed_data:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonValue'
              type: array
            - type: 'null'
          title: Detailed Data
          description: the result's rows, every one the result holds.
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
          description: rows in the result.
        truncated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Truncated
          description: true when the response does not carry every row.
        column_units:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: units per column.
        row_label:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: what a row represents.
        row_grain:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the row grain.
        presentation:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: presentation hints.
        status:
          type: string
          title: Status
          description: the run's outcome, such as succeeded or failed.
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: the builder conversation the draft belongs to.
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
          description: the builder message that was run.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: a note about the run.
        effective_controls:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the inputs the run actually used.
        data_through:
          anyOf:
            - type: string
            - type: 'null'
          title: Data Through
          description: the last date the data covers.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: the builder conversation in Edgeful AI.
      additionalProperties: true
      type: object
      required:
        - status
      title: CustomReportDraftRunResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReportControls:
      properties:
        ticker:
          anyOf:
            - type: string
              maxLength: 30
              minLength: 1
            - type: 'null'
          title: Ticker
          description: the ticker to run on, within the report's market.
        market_type:
          anyOf:
            - type: string
              enum:
                - futures
                - stock
                - forex
                - crypto
            - type: 'null'
          title: Market Type
          description: the report's market; any other market is refused.
        session:
          anyOf:
            - type: string
              maxLength: 80
              minLength: 1
            - $ref: '#/components/schemas/ReportSession'
            - type: 'null'
          title: Session
          description: a standard session name, or a custom window.
        start_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Start Date
          description: first date of the window, YYYY-MM-DD.
        end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: End Date
          description: >-
            last date of the window, YYYY-MM-DD; runs stop at the last completed
            session.
      additionalProperties: false
      type: object
      title: ReportControls
      description: >-
        Inputs a custom report run may change; the report's market and
        granularity stay locked.
    JsonValue: {}
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ReportSession:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 80
              minLength: 1
            - type: 'null'
          title: Name
          description: a label for the window.
        start_time:
          type: string
          pattern: ^\d{2}:\d{2}(:\d{2})?$
          title: Start Time
          description: start of the window as HH:MM or HH:MM:SS in the timezone.
        end_time:
          type: string
          pattern: ^\d{2}:\d{2}(:\d{2})?$
          title: End Time
          description: end of the window as HH:MM or HH:MM:SS in the timezone.
        timezone:
          type: string
          maxLength: 80
          minLength: 1
          title: Timezone
          description: IANA timezone the clocks are read in.
          default: America/New_York
      additionalProperties: false
      type: object
      required:
        - start_time
        - end_time
      title: ReportSession
      description: A custom session window that replaces the report's session for a run.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Send your Edgeful API key in the Authorization header as `Bearer
        <api-key>` (for example, `Bearer ef_live_<random>`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.